English
Docs menu

Agent Sandboxes docs · Tasks

SSH into a sandbox: shell, scp, SFTP and tunnels

Updated · 5 min read

Every sandbox takes plain ssh, scp, sftp and ssh -L: ssh <sandbox id>@<server> -p 2222, signed in with an SSH key of the workspace or a token as the password. A login wakes a paused sandbox, and nothing needs installing in it.

In short
  • Sandbox.ssh_command is the command: the sandbox's id as the user name, its server, port 2222.
  • Keys: SetSshKeys gives the workspace its public keys, which sign in to every sandbox; removing one ends its sessions.
  • Or a token: ConnectSandbox's token is the password, for a program or a sandbox you reach once.
  • A shell, SFTP and -L tunnels, into the sandbox alone, never into its server.

Step 1: Give the workspace your public key

SetSshKeys replaces the workspace's keys with the list it is given, so send the ones it has with yours. The console's workspace settings do the same, under SSH keys.

Python
from pathlib import Path

mine = (Path.home() / ".ssh" / "id_ed25519.pub").read_text().strip()
kept = [key.public_key for key in sandboxes.get_workspace().ssh_keys]
workspace = sandboxes.set_ssh_keys(ssh_keys=[*kept, mine])
print([key.fingerprint for key in workspace.ssh_keys])
# ['SHA256:EqzSrW++0DTmPtQLG+r1oKBoKzfKQRilcUFxx/p/Eyw']
TypeScript
import { readFile } from "node:fs/promises";
import { homedir } from "node:os";

const mine = (await readFile(`${homedir()}/.ssh/id_ed25519.pub`, "utf8")).trim();
const kept = (await sandboxes.getWorkspace()).sshKeys.map((key) => key.publicKey);
const workspace = await sandboxes.setSshKeys({ sshKeys: [...kept, mine] });
console.log(workspace.sshKeys.map((key) => key.fingerprint));
Go
home, _ := os.UserHomeDir()
mine, err := os.ReadFile(home + "/.ssh/id_ed25519.pub")
if err != nil {
	log.Fatal(err)
}
current, err := client.GetWorkspace(ctx, &sandboxes.GetWorkspaceRequest{})
if err != nil {
	log.Fatal(err)
}
keys := []string{strings.TrimSpace(string(mine))}
for _, key := range current.SSHKeys {
	keys = append(keys, key.PublicKey)
}
workspace, err := client.SetSSHKeys(ctx, &sandboxes.SetSSHKeysRequest{SSHKeys: keys})
if err != nil {
	log.Fatal(err)
}
fmt.Println(len(workspace.SSHKeys))
Rust
let mine = std::fs::read_to_string(format!("{}/.ssh/id_ed25519.pub", std::env::var("HOME")?))?;
let current = sandboxes.get_workspace(GetWorkspaceRequest::default()).await?;
let mut keys: Vec<String> = current.ssh_keys.into_iter().map(|key| key.public_key).collect();
keys.push(mine.trim().to_string());
let workspace = sandboxes
    .set_ssh_keys(SetSshKeysRequest { ssh_keys: keys, ..Default::default() })
    .await?;
println!("{}", workspace.ssh_keys.len());

Step 2: Take the sandbox's SSH command

A sandbox's record has its ssh_command. It changes only when a stopped sandbox starts on another server, so read it from the record rather than keeping it.

Python
print(sandboxes.get_sandbox(sandbox_id).ssh_command)
# ssh [email protected] -p 2222
TypeScript
console.log((await sandboxes.getSandbox({ sandboxId })).sshCommand);
Go
record, err := client.GetSandbox(ctx, &sandboxes.GetSandboxRequest{SandboxID: id})
if err != nil {
	log.Fatal(err)
}
fmt.Println(record.SSHCommand)
Rust
let record = sandboxes
    .get_sandbox(GetSandboxRequest { sandbox_id: id.clone(), ..Default::default() })
    .await?;
println!("{}", record.ssh_command);
CLI
$ pethost sandbox show api-dev
id          e9bprbw1hovj6sw5
name        api-dev
state       running since 01:19
next        paused today at 01:29, unless something happens in it
size        default, disk 20 GiB
template    base@17
port 5173   https://5173-e9bprbw1hovj6sw5.sbx1.sandboxes.pethost.network
ssh         ssh [email protected] -p 2222
panel       https://console.pethost.dev/w/af6hvmyk/sandboxes/e9bprbw1hovj6sw5
used        running 6 min 17 s
created     today at 01:19
MCP
GetSandbox {"sandbox_id": "…"}

Step 3: Sign in

$ ssh [email protected] -p 2222
user@e9bprbw1hovj6sw5:~$

The shell runs as user in /home/user, with sudo. A paused sandbox wakes as you sign in, and stays awake while the session is open.

Without a key: a token as the password

ConnectSandbox answers a token for one sandbox, good for an hour unless ttl_seconds says otherwise, up to 86,400 s, and the same ssh_command: the token is its password. It suits a program, or a person who reaches a sandbox once. The token is root in that sandbox: keep it out of logs and messages. UpdateSandbox with revoke_tokens makes every token and link made for the sandbox stop working.

pethost sandbox shell <id> does all of this for you: it asks for a token and opens the shell in your terminal, with nothing to set up, and runs a command after -- on a terminal too.

$ pethost sandbox shell api-dev -- uptime
 00:25:49 up 6 min,  0 user,  load average: 0.04, 0.04, 0.00

Files and tunnels

The same address and port serve scp and sftp, and forward ports with -L:

scp -P 2222 ./data.csv [email protected]:data/
sftp -P 2222 [email protected]
ssh -N -L 5173:localhost:5173 [email protected] -p 2222

A tunnel reaches any port in the sandbox, ports bound to localhost included, so it opens a private port in your own browser at http://localhost:5173 with no token (ports and previews).

How it works

No SSH server runs in the sandbox. The server it runs on answers port 2222: it checks the key or the token before anything wakes, then runs your shell as a process on a terminal of the sandbox, SFTP as a program in it, and a tunnel straight to the port. It reaches that one sandbox and nothing of the server itself. A command you run over SSH is listed by ListCommands while it runs, and its end is an event, started by SSH.

  • A login wakes a paused sandbox, in about 0.1 s. A stopped one wakes so only with wake_when_stopped; else the login is refused with “stopped: resume it”, and ResumeSandbox starts it.
  • An open session keeps the sandbox awake, and counts as RUNNING. Close it, and the idle timers start.
  • Removing a key ends its sessions in every sandbox of the workspace.
  • A session takes 64 variables from your client at most.

When it does not work

  • “Permission denied (publickey,password)”: the key is not one of the workspace's, or the token expired. Add the key with SetSshKeys, or ask ConnectSandbox for a fresh token.
  • “stopped: resume it”: the sandbox is stopped. ResumeSandbox starts it, its files as it left them.
  • The connection times out: a firewall on your side blocks port 2222. Try from another network, or use pethost sandbox shell, which needs the same port.
  • The address no longer answers for the sandbox: a stopped sandbox started on another server, with a new ssh_command. Read it from the record again.
  • A session ended by itself: its key was removed, or the sandbox's tokens were revoked.

Questions

How do I SSH into a sandbox?

Add your public key to the workspace, then run the sandbox's ssh_command: ssh <sandbox id>@<server> -p 2222.

Can I use scp and SFTP?

Yes, at the same address with -P 2222, and ssh -L forwards its ports.

Does SSH wake a paused sandbox?

Yes, at login, in about 0.1 s, and the open session keeps it awake.

Can I SSH into the server a sandbox runs on?

No. A login reaches its sandbox alone.

Do I need to install an SSH server in the sandbox?

No. The sandbox's server answers SSH and runs your shell inside the sandbox.

Try Pethost Agent Sandboxes

A 7-day trial with $1 of usage and 4 vCPUs, with a card. Then a plan from $20 a month, which includes as much usage.

Start the trial