Skip to content
pols.so docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

SSH

Open shells, run commands, copy files and forward ports over SSH through the pols gateway.

Every running sandbox is reachable over SSH through the gateway at ssh.pols.so. Register your public key once, and it opens every running sandbox of your org.

pols ssh-key add ~/.ssh/id_ed25519.pub
pols ssh web                  # an interactive shell
pols ssh web -- uname -a      # one command
pols ssh web --print          # the plain ssh command, to use with scp, sftp or your own options

Keys

pols ssh-key add ~/.ssh/id_ed25519.pub   # register a key (the comment becomes its label)
pols ssh-key ls                          # registered keys with their IDs and fingerprints
pols ssh-key rm KEY                      # remove one; open sessions stay open

Keys belong to the org, not to a sandbox: any registered key opens every running sandbox of the org, including sandboxes created later. Register a colleague’s key to let them in, and remove it to stop new logins. Over the API, keys are managed at /v1/ssh-keys.

How the gateway works

The gateway routes by user name: you connect as <sandbox ID>@ssh.pols.so, and it checks your key with the control plane, then logs into the sandbox’s SSH server as user with a certificate that is valid for two minutes. Shells, commands, scp, sftp, agent forwarding and port forwarding are relayed.

The gateway currently listens on port 2222 and will move to port 22. pols ssh and pols ssh --print always use the right port, as does GET /v1/sandboxes/{sandbox}/ssh, which returns the host, port, user and the full command.

$ pols ssh web --print
ssh -p 2222 sbx_...@ssh.pols.so

Use the printed command with standard tools:

scp -P 2222 ./data.csv sbx_...@ssh.pols.so:/home/user/
ssh -p 2222 -L 5432:localhost:5432 sbx_...@ssh.pols.so    # reach the sandbox's Postgres on your machine

The gateway only accepts keys registered with pols ssh-key add; keys you add to ~/.ssh/authorized_keys inside the sandbox do not open it from outside, because the sandbox’s own SSH server is not reachable from the internet. Password logins are off.

When it does not connect

  • The sandbox must be running. Resume a stopped one with pols resume.
  • Your key must be registered: check pols ssh-key ls and compare the fingerprint with ssh-keygen -lf ~/.ssh/id_ed25519.pub.
  • Use the sandbox ID, not its name, as the SSH user name. pols ssh resolves names for you.