Agent Sandboxes docs · Tasks
SSH into a sandbox: shell, scp, SFTP and tunnels
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.
Sandbox.ssh_commandis the command: the sandbox's id as the user name, its server, port 2222.- Keys:
SetSshKeysgives 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
-Ltunnels, 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.
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']
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));
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))
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.
print(sandboxes.get_sandbox(sandbox_id).ssh_command)
# ssh [email protected] -p 2222
console.log((await sandboxes.getSandbox({ sandboxId })).sshCommand);
record, err := client.GetSandbox(ctx, &sandboxes.GetSandboxRequest{SandboxID: id})
if err != nil {
log.Fatal(err)
}
fmt.Println(record.SSHCommand)
let record = sandboxes
.get_sandbox(GetSandboxRequest { sandbox_id: id.clone(), ..Default::default() })
.await?;
println!("{}", record.ssh_command);
$ 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
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”, andResumeSandboxstarts 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 askConnectSandboxfor a fresh token. - “stopped: resume it”: the sandbox is stopped.
ResumeSandboxstarts 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.