Skip to content

Instantly share code, notes, and snippets.

@kcosr
Created July 21, 2026 14:43
Show Gist options
  • Select an option

  • Save kcosr/dfd66fed70ee121c9c6e9dca2ec88dbe to your computer and use it in GitHub Desktop.

Select an option

Save kcosr/dfd66fed70ee121c9c6e9dca2ec88dbe to your computer and use it in GitHub Desktop.
Standalone Ubuntu SSH Container on a Mac

Standalone Ubuntu SSH Container on a Mac

This guide creates a minimal Ubuntu workstation with Apple's container CLI. OpenSSH runs directly as PID 1, with a persistent Linux home and a shared Mac directory.

Because sshd is PID 1, the container exits if sshd exits. Start it again from the Mac with container start ubuntu-ssh.

The container has a persistent ext4 home and one Mac directory shared into that home:

Apple ext4 volume  -> /home/<user>
Mac ~/shared       -> /home/<user>/shared

The ext4 home is recommended for a workstation because it preserves Linux file ownership, permissions, symlinks, repositories, and user-installed tools when the container is replaced. The shared directory is deliberately outside the isolation boundary; do not mount the entire Mac home directory.

Requirements

Use an Apple silicon Mac running a macOS version supported by the installed Apple Container release. Install the latest signed package from Apple Container releases.

Apple's current documentation describes host-directory mounts and loopback port forwarding and the complete container command reference. The project is pre-1.0, so consult the documentation for the installed release if an option has changed.

Start the service:

container system start

Create the image files

Create a small build directory:

mkdir -p "$HOME/apple-ubuntu-ssh"
cd "$HOME/apple-ubuntu-ssh"

Save this as Containerfile:

FROM ubuntu:24.04

ENV DEBIAN_FRONTEND=noninteractive

ARG USER_NAME=dev
ARG USER_UID=1000
ARG USER_GID=1000

RUN apt-get update \
 && apt-get install -y --no-install-recommends \
      bash \
      ca-certificates \
      curl \
      git \
      less \
      openssh-client \
      openssh-server \
      procps \
      vim-tiny \
 && rm -rf /var/lib/apt/lists/*

RUN set -eux; \
    userdel -r ubuntu 2>/dev/null || true; \
    if getent passwd "$USER_UID" >/dev/null; then \
      echo "uid $USER_UID is already in use" >&2; exit 1; \
    fi; \
    if getent group "$USER_GID" >/dev/null; then \
      user_group="$(getent group "$USER_GID" | cut -d: -f1)"; \
    else \
      groupadd --gid "$USER_GID" "$USER_NAME"; \
      user_group="$USER_NAME"; \
    fi; \
    useradd --uid "$USER_UID" --gid "$user_group" \
      --create-home --shell /bin/bash "$USER_NAME"; \
    passwd -d "$USER_NAME"

ENV DEV_USER=${USER_NAME} \
    DEV_UID=${USER_UID} \
    DEV_GID=${USER_GID}

COPY authorized_key /usr/local/share/container-authorized-key
COPY start-sshd /usr/local/sbin/start-sshd

RUN chmod 0644 /usr/local/share/container-authorized-key \
 && chmod 0755 /usr/local/sbin/start-sshd \
 && mkdir -p /run/sshd /etc/ssh/sshd_config.d \
 && rm -f /etc/ssh/ssh_host_* \
 && printf '%s\n' \
      'AuthenticationMethods publickey' \
      'PasswordAuthentication no' \
      'KbdInteractiveAuthentication no' \
      'PermitRootLogin no' \
      'PubkeyAuthentication yes' \
      'AuthorizedKeysFile .ssh/authorized_keys' \
      'AllowAgentForwarding no' \
      'AllowTcpForwarding local' \
      'GatewayPorts no' \
      'X11Forwarding no' \
      'PermitTunnel no' \
      'PermitUserEnvironment no' \
      > /etc/ssh/sshd_config.d/00-standalone.conf

EXPOSE 22
ENTRYPOINT ["/usr/local/sbin/start-sshd"]

Save this as start-sshd:

#!/usr/bin/env bash
set -euo pipefail

home_dir="/home/$DEV_USER"

# The ext4 volume hides the home created in the image, so initialize the
# mounted home on every start. Only the public key is copied into it.
install -d -o "$DEV_UID" -g "$DEV_GID" -m 0750 "$home_dir"
install -d -o "$DEV_UID" -g "$DEV_GID" -m 0700 "$home_dir/.ssh"
install -o "$DEV_UID" -g "$DEV_GID" -m 0600 \
  /usr/local/share/container-authorized-key \
  "$home_dir/.ssh/authorized_keys"

mkdir -p /run/sshd
ssh-keygen -A
/usr/sbin/sshd -t

exec /usr/sbin/sshd -D -e -o "AllowUsers=$DEV_USER"

Make the startup file executable:

chmod 0755 start-sshd

Run the setup script

Save the following as setup.sh in the same directory. It generates a dedicated SSH key, builds the image using the Mac user's UID/GID, creates a 64-GiB ext4 home volume, starts the container, and writes the ubuntu-ssh Mac SSH alias.

#!/usr/bin/env bash
set -euo pipefail

container_name="${CONTAINER_NAME:-ubuntu-ssh}"
image_name="${IMAGE_NAME:-local/ubuntu-ssh:24.04}"
volume_name="${HOME_VOLUME_NAME:-ubuntu-ssh-home}"
ssh_alias="${SSH_ALIAS:-ubuntu-ssh}"
ssh_port="${SSH_PORT:-2222}"
linux_user="${LINUX_USER:-$(id -un)}"
linux_uid="$(id -u)"
linux_gid="$(id -g)"
shared_dir="${SHARED_DIR:-$HOME/shared}"
key_dir="$HOME/.ssh/apple-ubuntu"
key_file="$key_dir/id_ed25519"
ssh_config="$HOME/.ssh/config"
ssh_config_dir="$HOME/.ssh/config.d"

fail() { printf 'error: %s\n' "$*" >&2; exit 1; }

[[ "$linux_user" =~ ^[a-z_][a-z0-9_-]*$ ]] \
  || fail "LINUX_USER must be a lowercase Unix account name"
[[ "$ssh_port" =~ ^[0-9]+$ && "$ssh_port" -ge 1024 && "$ssh_port" -le 65535 ]] \
  || fail "SSH_PORT must be from 1024 through 65535"
[[ -f Containerfile && -x start-sshd ]] \
  || fail "run this script from the directory containing Containerfile and start-sshd"

container system start
container inspect "$container_name" >/dev/null 2>&1 \
  && fail "container $container_name already exists"

install -d -m 0700 "$key_dir" "$HOME/.ssh" "$ssh_config_dir"
mkdir -p "$shared_dir"

if [[ ! -f "$key_file" ]]; then
  ssh-keygen -t ed25519 -N '' -f "$key_file" \
    -C "$linux_user@$container_name"
fi
chmod 0600 "$key_file"
chmod 0644 "$key_file.pub"
install -m 0644 "$key_file.pub" authorized_key

container build \
  --build-arg "USER_NAME=$linux_user" \
  --build-arg "USER_UID=$linux_uid" \
  --build-arg "USER_GID=$linux_gid" \
  --tag "$image_name" \
  --file Containerfile \
  .

container volume inspect "$volume_name" >/dev/null 2>&1 \
  || container volume create -s 64g "$volume_name"

container run --detach \
  --name "$container_name" \
  --cpus 4 \
  --memory 4g \
  --publish "127.0.0.1:$ssh_port:22" \
  --mount "type=volume,source=$volume_name,target=/home/$linux_user" \
  --volume "$shared_dir:/home/$linux_user/shared" \
  "$image_name"

# Put Include first so a broad Host * block cannot win before the alias file.
if [[ ! -f "$ssh_config" ]] \
  || ! grep -Eq '^[[:space:]]*Include[[:space:]]+~/.ssh/config\.d/\*' "$ssh_config"; then
  config_tmp="$ssh_config.tmp.$$"
  {
    printf 'Include ~/.ssh/config.d/*\n'
    [[ ! -f "$ssh_config" ]] || cat "$ssh_config"
  } > "$config_tmp"
  chmod 0600 "$config_tmp"
  mv "$config_tmp" "$ssh_config"
fi

cat > "$ssh_config_dir/$ssh_alias" <<EOF
Host $ssh_alias
    HostName 127.0.0.1
    Port $ssh_port
    User $linux_user
    IdentityFile $key_file
    IdentitiesOnly yes
    StrictHostKeyChecking accept-new
EOF
chmod 0600 "$ssh_config_dir/$ssh_alias"

for attempt in {1..30}; do
  if ssh -o BatchMode=yes -o ConnectTimeout=2 "$ssh_alias" true; then
    printf 'ready: ssh %s\n' "$ssh_alias"
    exit 0
  fi
  sleep 1
done

container logs "$container_name" >&2 || true
fail "SSH did not become ready"

Run it:

chmod 0755 setup.sh
./setup.sh

Override the loopback port or Linux username if needed:

SSH_PORT=2223 LINUX_USER=dev ./setup.sh

The script refuses to replace an existing container.

Connect and manage the container

Connect through the generated alias:

ssh ubuntu-ssh

Stop and restart it:

container stop ubuntu-ssh
container start ubuntu-ssh

View PID-1/SSH output:

container logs ubuntu-ssh

The SSH user has no sudo. Install an Ubuntu system package deliberately from the Mac as container root:

container exec ubuntu-ssh bash -lc \
  'apt-get update && apt-get install -y htop'

Packages installed this way survive stop/start but are part of the container's writable layer. The ext4 home and Mac shared folder are the durable locations.

Rebuild while preserving home

After editing Containerfile or start-sshd, replace the container and rerun setup:

container stop ubuntu-ssh
container delete ubuntu-ssh
ssh-keygen -R '[127.0.0.1]:2222'
./setup.sh

The named ubuntu-ssh-home volume is not deleted, so the Linux home survives. The replacement gets new SSH host keys; removing the old loopback host-key entry is therefore expected. Substitute the configured port if it is not 2222.

Do not delete the named home volume unless the persistent Linux home should also be destroyed.

Security boundaries

  • SSH is bound to 127.0.0.1, not the Mac's network interfaces.
  • Authentication is public-key only; root and password login are disabled.
  • The private key remains on the Mac. Only its public half enters the image.
  • Agent forwarding, remote forwarding, X11, and tunnels are disabled. Local forwarding remains available for development servers.
  • The container can access only Mac files explicitly placed under ~/shared.
  • This setup does not restrict or inspect outbound traffic. It provides Apple Container VM/container isolation, not an egress security policy.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment