---
title: SSH
description: 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.

```sh
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

```sh
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.

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

Use the printed command with standard tools:

```sh
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.