---
title: "SSH into a sandbox: shell, scp, SFTP and tunnels | Pethost Agent Sandboxes"
description: "Sign in to any sandbox with plain ssh, copy files with scp and SFTP, and forward its ports with ssh -L, with a workspace key or a token as the password."
---

[Agent Sandboxes docs](https://pethost.dev/docs/sandboxes/) · Tasks

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

Updated 22 November 2026 · 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 e9bprbw1hovj6sw5@sbx1.sandboxes.pethost.network -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 e9bprbw1hovj6sw5@sbx1.sandboxes.pethost.network -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 e9bprbw1hovj6sw5@sbx1.sandboxes.pethost.network -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 k7f3q2xy0a1b2c3d@sbx1.sandboxes.pethost.network:data/
sftp -P 2222 k7f3q2xy0a1b2c3d@sbx1.sandboxes.pethost.network
ssh -N -L 5173:localhost:5173 k7f3q2xy0a1b2c3d@sbx1.sandboxes.pethost.network -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](https://pethost.dev/docs/sandboxes/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.

[PreviousVolumes: a disk that outlives sandboxes](https://pethost.dev/docs/sandboxes/volumes/) [NextObservability: a sandbox's metrics, events and usage](https://pethost.dev/docs/sandboxes/observability/)

## 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](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Templates](https://pethost.dev/templates/)
- [About](https://pethost.dev/about/)
- [Docs](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Terms](https://pethost.dev/terms/)
- [Privacy](https://pethost.dev/privacy/)
- [Refunds](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Databases

- [Postgres](https://pethost.dev/postgres/)
- [Valkey](https://pethost.dev/valkey/)

Agent Sandboxes

- [Sandboxes](https://pethost.dev/sandboxes/)
- [Pricing](https://pethost.dev/sandboxes/#pricing)
- [Docs](https://pethost.dev/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Comparisons

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/blog/coolify-cloud-vs-dokploy-cloud/)
- [Railway vs Render vs Fly.io pricing](https://pethost.dev/blog/railway-vs-render-vs-fly-io-pricing/)
- [Managed Docker Compose hosting](https://pethost.dev/blog/managed-docker-compose-hosting/)

Alternatives

- [Railway alternatives](https://pethost.dev/blog/railway-alternatives/)
- [Heroku alternatives](https://pethost.dev/blog/heroku-alternatives/)
- [Dokploy alternatives](https://pethost.dev/blog/dokploy-alternatives/)
- [Coolify alternatives](https://pethost.dev/blog/coolify-alternatives/)
- [Render alternatives](https://pethost.dev/blog/render-alternatives/)
- [Sliplane alternatives](https://pethost.dev/blog/sliplane-alternatives/)
