#SSH

Use standard SSH clients to open a shell inside a sandbox or copy files with scp. Sandbox0 terminates SSH at a region-scoped ssh-gateway, authenticates the user from uploaded SSH public keys, and bridges the session into the sandbox runtime.

Connection Model#

The gateway uses the SSH username to decide which sandbox to connect to. Your uploaded public key identifies the user, and the platform still enforces normal sandbox authorization before opening the session.

Most clients should read the connection info from GET /api/v1/sandboxes/{'{id}'} instead of hard-coding a region host. The response includes:

json
{
  "ssh": {
    "host": "aws-us-east-1.ssh.sandbox0.example.com",
    "port": 22,
    "username": "rs-abc123-default-x7k9m"
  }
}

Manage SSH Public Keys#

Upload your SSH public key once, then reuse standard ssh, scp, and sftp clients.

Create Request Body#

SSH Public Key Object#

bash
curl -X POST "$SANDBOX0_BASE_URL/users/me/ssh-keys" \
  -H "Authorization: Bearer $SANDBOX0_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "laptop",
    "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExample user@host"
  }'

List the keys currently attached to your user:

bash
curl "$SANDBOX0_BASE_URL/users/me/ssh-keys" \
  -H "Authorization: Bearer $SANDBOX0_TOKEN"

Delete a key you no longer want to trust:

bash
curl -X DELETE "$SANDBOX0_BASE_URL/users/me/ssh-keys/$KEY_ID" \
  -H "Authorization: Bearer $SANDBOX0_TOKEN"

Connect to a Sandbox#

Read ssh.host, ssh.port, and ssh.username from the sandbox detail response, then connect with a standard SSH client.

Fetch the connection info:

bash
curl "$SANDBOX0_BASE_URL/api/v1/sandboxes/$SANDBOX_ID" \
  -H "Authorization: Bearer $SANDBOX0_TOKEN"

Use the returned values with ssh:

bash
ssh -p 22 [email protected]

Run a one-shot remote command instead of opening an interactive shell:

bash
ssh -p 22 [email protected] 'uname -a'

If the sandbox is paused, ssh-gateway asks the control plane to resume it before attaching the session.

Copy Files with scp#

Use standard scp to upload or download files. The default OpenSSH mode is supported.

Upload a local file:

bash
scp -P 22 ./build.log [email protected]:/workspace/build.log

Download a file from the sandbox:

bash
scp -P 22 [email protected]:/workspace/output.txt ./output.txt

Because scp runs over the SFTP subsystem here, sftp clients work too:

bash
sftp -P 22 [email protected]

Operational Notes#

• SSH authorization stays at the platform layer. You do not manage authorized_keys inside each sandbox.
• Uploaded SSH public keys belong to the user account, not to one sandbox.
• A key can access any sandbox that the user is authorized to access in that region.
• SSH is best for human shell access and standard file transfer. For programmatic process control, use Contexts.

Next Steps#