You can ssh, sftp, and scp into a box through a dedicated SSH gateway (the zomg-ssh-gateway crate, deployed via k8s/zomg-ssh-gateway.yaml). It runs separately from zomg-api, so no box pod has to run sshd and your SSH sessions survive zomg-api restarts. For day-to-day client usage, see SSH via the gateway and the zomg ssh command. This page covers how the gateway works and how operators configure it.

​
Addressing

The SSH username selects the target box as <project>--<box>, and the gateway listens on port 2222: 
ssh -p 2222 myproject--dev@ssh.<zomg_domain>
sftp -P 2222 myproject--dev@ssh.<zomg_domain>
To skip typing the port each time, add an SSH config alias: 
Host zomg-ssh
  HostName ssh.<zomg_domain>
  Port 2222

ssh myproject--dev@zomg-ssh
The zomg ssh <box> command builds this address for you from the active profile.

​
Authentication

The gateway accepts public keys from two sources, both configured on the gateway Deployment:
  • ZOMG_SSH_GITHUB_USERS: a comma-separated list of GitHub usernames. Their public keys are fetched from GitHub and refreshed periodically (ZOMG_SSH_KEYS_REFRESH_SECS, default 300s).
  • ZOMG_SSH_AUTHORIZED_KEYS: optional static OpenSSH authorized_keys content, loaded from the Kubernetes secret provisioned by Ansible.

​
Host key

The gateway loads a stable host key from /var/lib/boxes/ssh/host-ed25519 (overridable via ZOMG_SSH_HOST_KEY_PATH), mounted from a Kubernetes secret. A persistent key avoids host-key-changed warnings across redeploys. Generate it once and store it in SOPS, then retrieve and apply it as a secret: 
# generate (one-time)
ssh-keygen -t ed25519 -f certs/ssh/host-ed25519 -N ''

# save the key into the SOPS deploy secret
./scripts/save-ssh-hostkey.sh certs/ssh/host-ed25519

# retrieve from SOPS and create/update the k8s secret (namespace boxes-system)
./scripts/get-ssh-hostkey.sh --apply
If the k3s API (:6443) is not reachable locally, apply by SSHing into the VM and running kubectl there: 
./scripts/get-ssh-hostkey.sh --apply-via-vm
The VM host is resolved from ZOMG_DEPLOY_SSH_HOST / ZOMG_VM_SSH_HOST or the profile’s deploy_ssh_host / ssh_host.

​
How it works

The gateway terminates the SSH connection and resolves the target pod by its zomg.ai/project and box labels. It prefers entering the box via CRI/containerd: it uses nsenter into the container’s mount and network namespaces and runs the requested shell, SFTP, or exec command under chroot /volumes. If CRI initialization or session start fails, it falls back to Kubernetes exec (kubectl exec). PTY sessions negotiate terminal size and force TERM=xterm-256color.

​
Base requirements

SFTP requires an sftp-server binary in the base image (the openssh-sftp-server package), which the box base installs. The gateway looks for it at /usr/lib/openssh/sftp-server, /usr/libexec/sftp-server, or on PATH.

​
Limitations

  • No port forwarding: ssh -L / ssh -R and direct-tcpip channels are not supported.