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.
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 startCreate 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-sshdSave 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.shOverride the loopback port or Linux username if needed:
SSH_PORT=2223 LINUX_USER=dev ./setup.shThe script refuses to replace an existing container.
Connect through the generated alias:
ssh ubuntu-sshStop and restart it:
container stop ubuntu-ssh
container start ubuntu-sshView PID-1/SSH output:
container logs ubuntu-sshThe 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.
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.shThe 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.
- 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.