You can ssh, sftp, and scp into a box through a dedicated SSH gateway. 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.

​
Addressing

The SSH username selects the target box and the identity to run as, and the gateway listens on port 2222. <project>--<box>--<user> runs the session as that deployment user; <project>--<box> runs it as root: 
ssh -p 2222 myproject--dev--alice@ssh.zomg.ai
ssh -p 2222 myproject--dev@ssh.zomg.ai        # root session
sftp -P 2222 myproject--dev--alice@ssh.zomg.ai
To skip typing the port each time, add an SSH config alias: 
Host zomg-ssh
  HostName ssh.zomg.ai
  Port 2222

ssh myproject--dev--alice@zomg-ssh
The zomg ssh <box> command builds this address for you from the active profile: signed in as a user it emits the <project>--<box>--<user> form, --root emits the root form, and --user <name> picks any deployment user. zomg ssh <box> --info prints the resolved ssh command without connecting.

​
Authentication

Authentication is by SSH public key, and keys are bound to identities:
  • Your deployment user’s authorized_keys authenticate the <project>--<box>--<user> form, for your own user only.
  • Operator-authorized keys (for example GitHub usernames the instance trusts) work for every address form, including the root <project>--<box> form.
Root sessions always require an operator-authorized key — a deployment user’s key never grants root or another user’s identity. If your key is rejected, ask your operator to add your public key to your deployment user or to authorize your GitHub username. zomg ssh <box> builds the right address and user for you; authorization itself is the instance’s setting.

​
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, network, PID, UTS, and IPC namespaces and runs the requested shell, SFTP, or exec command under chroot /volumes — so sessions see the box’s process tree and hostname, and tools like ps, pgrep, and pkill act on box processes. 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.