> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boat.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# SSH

> Open a shell in a sandbox, run commands, forward a port to your computer, connect VS Code or another SSH client, and copy files in and out.

Run `boat ssh <id>` for a shell. The CLI creates the SSH key, authorizes it on the sandbox and checks the host key for you.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
boat ssh bx_f7k2q9hd
```

In the dashboard, **Copy SSH** in the row menu of a sandbox copies this command.

## Run commands

* For a script or an agent, use `boat exec`. It is faster than `boat ssh` because it opens no SSH session.
* For a long-running server, add `--detach`. A normal command stops after 30 seconds by default. Read [Background commands](https://docs.boat.dev/long-running-tasks/background-commands.md).
* In an integration, use the command API. The examples use `BOAT_API_BASE=https://boat.dev/api/v1`.

```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
boat exec bx_f7k2q9hd --cwd my-repo "npm test"
boat ssh bx_f7k2q9hd "cd /home/user/my-repo && npm test"
boat ssh bx_f7k2q9hd -- bash -s < ./setup.sh
```

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/commands" \
  -H "Authorization: Bearer $BOAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command":"npm test","cwd":"my-repo","timeoutSeconds":60}'
```

```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
const result = await sandbox.command({
  sandboxId: "bx_f7k2q9hd",
  command: "npm test", cwd: "my-repo", timeoutSeconds: 60,
});
console.log(result.stdout);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
from boat_sdk.models.command_request import CommandRequest

result = sandbox.command(
    "bx_f7k2q9hd",
    CommandRequest(command="npm test", cwd="my-repo", timeout_seconds=60),
)
print(result.actual_instance.stdout)   # command() returns a wrapper
```

`boat ssh` and `boat exec` without an id use the last sandbox that you created or forked in this terminal. This needs the shell function that the installer adds. In scripts, always pass the id.

> [!NOTE]
>
> * SSH works only while the sandbox runs. Resume a stopped sandbox first.
> * In the first seconds of a start or a resume, SSH can answer `sandbox_restoring` or `sandbox_securing`. Retry a few seconds later. The CLI retries for you.

## Forward a port

Use `boat forward` to reach a port of the sandbox on your own computer. Nothing becomes public. It works for any TCP service, for example a database.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
boat forward bx_f7k2q9hd --remote 5432                 # sandbox 127.0.0.1:5432 -> your localhost:5432
boat forward bx_f7k2q9hd --remote 3000 --local 8080    # sandbox port 3000 -> your localhost:8080
boat forward bx_f7k2q9hd --reverse --local 7777        # your localhost:7777 -> sandbox 127.0.0.1:7777
```

* The command runs until you press Ctrl+C. It connects again by itself after a network drop.
* `--bind` changes the listen address. The default is `127.0.0.1`.
* The API key needs the `ssh` action.

For a URL that other people can open, read [Public URLs](https://docs.boat.dev/hosting).

## Use VS Code, Cursor or another SSH client

The full setup, with an `~/.ssh/config` block, is on [VS Code, Cursor and SSH config](https://docs.boat.dev/ssh-access/editors.md). In short:

1. Authorize your public key on the sandbox.
2. Connect to `sshEndpoint` when it is set. Else connect to `machineIp` on port 22.
3. Pin the host key from the API response.
4. Do steps 1 to 3 again after each resume and fork. The machine, its IP address and its host key change.

The curl tab does all three steps. It uses your own key `~/.ssh/id_ed25519`.

```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
boat ssh bx_f7k2q9hd true   # authorizes ~/.ssh/ascii_box_ed25519 and pins the host key for boat ssh
boat info bx_f7k2q9hd       # "ip", and "sshEndpoint" (host:port) when the sandbox has no public IPv4
ssh -i ~/.ssh/ascii_box_ed25519 user@<ip>                   # when sshEndpoint is null
ssh -i ~/.ssh/ascii_box_ed25519 -p <port> user@<host>       # when sshEndpoint is "host:port"
```

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
resp="$(curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/sshkey" \
  -H "Authorization: Bearer $BOAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"key\":\"$(cat ~/.ssh/id_ed25519.pub)\"}")"

echo "bx_f7k2q9hd $(echo "$resp" | jq -r .hostKey)" > ~/.ssh/known_hosts_bx_f7k2q9hd

# sshEndpoint ("host:port") is set when the sandbox has no public IPv4 of its own
endpoint="$(echo "$resp" | jq -r '.sshEndpoint // empty')"
host="${endpoint%:*}"; port="${endpoint##*:}"
[ -n "$endpoint" ] || { host="$(echo "$resp" | jq -r .machineIp)"; port=22; }

ssh -p "$port" -i ~/.ssh/id_ed25519 \
    -o StrictHostKeyChecking=yes \
    -o UserKnownHostsFile=~/.ssh/known_hosts_bx_f7k2q9hd \
    -o HostKeyAlias=bx_f7k2q9hd \
    user@"$host"
```

```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
const { hostKey, machineIp, sshEndpoint } = await sandbox.sshKey({
  sandboxId: "bx_f7k2q9hd",
  key: "ssh-ed25519 AAAAC3Nza... you@example.com",
});
// write `bx_f7k2q9hd ${hostKey}` to a known_hosts file, then connect with HostKeyAlias=bx_f7k2q9hd
// to sshEndpoint ("host:port") when it is set, else to machineIp on port 22
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
from boat_sdk.models.ssh_key_request import SshKeyRequest

resp = sandbox.ssh_key("bx_f7k2q9hd", SshKeyRequest(key="ssh-ed25519 AAAAC3Nza... you@example.com"))
# write f"bx_f7k2q9hd {resp.host_key}" to a known_hosts file, then connect with HostKeyAlias=bx_f7k2q9hd
# to resp.ssh_endpoint ("host:port") when it is set, else to resp.machine_ip on port 22
```

* The CLI tab trusts the host key on the first connection. Use the curl tab to pin the key.
* The host key comes over your API connection, not over SSH. You can trust it without a first-connection prompt.
* An authorized key stays in `~/.ssh/authorized_keys` on the sandbox. Stop, resume and fork keep it.
* The CLI key file keeps its old name, `~/.ssh/ascii_box_ed25519`.

### "REMOTE HOST IDENTIFICATION HAS CHANGED"

Every resume and every fork runs the sandbox on a new machine with a new host key. `boat ssh` and `boat scp` get the new key for you. For another client, call the SSH key endpoint again and replace the line in your known\_hosts file.

## Copy files

* From a terminal, use `boat scp` with the sandbox ID as the remote host. Add `-r` for a folder.
* In an integration, use the file and artifact API calls.

```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
boat scp ./local-file.txt bx_f7k2q9hd:/home/user/
boat scp bx_f7k2q9hd:/home/user/output.zip ./output.zip
boat scp -r ./my-folder bx_f7k2q9hd:/home/user/
```

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
curl -sS -X PUT "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/files" \
  -H "Authorization: Bearer $BOAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"notes/input.txt","content":"hello\n","encoding":"utf8"}'

curl -L -o output.zip "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/artifacts?path=output.zip" \
  -H "Authorization: Bearer $BOAT_API_KEY"
```

```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
await sandbox.writeFile({
  sandboxId: "bx_f7k2q9hd",
  path: "notes/input.txt", content: "hello\n", encoding: "utf8",
});

const artifact = await sandbox.artifact({ sandboxId: "bx_f7k2q9hd", path: "output.zip" });
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
from boat_sdk.models.file_write_request import FileWriteRequest

sandbox.write_file("bx_f7k2q9hd", FileWriteRequest(
    path="notes/input.txt",
    content="hello\n",
    encoding="utf8",
))
artifact = sandbox.artifact("bx_f7k2q9hd", "output.zip")
```

File read and write paths follow these rules:

| Path | Rule |
| - | - |
| Relative | boat resolves it from the sandbox work directory, `/home/user`. |
| Absolute | It must resolve under `/home/user` or `/tmp`. |
| Absolute, outside these roots | boat refuses it with a 400 `invalid_path` error. The error names the allowed roots. |

### Large files

The JSON file calls stop at 5 MiB. For a larger file, ask for a signed URL and send the bytes straight to the sandbox. The sandbox serves the URL itself. So boat sets no size limit, and the transfer needs no Authorization header.

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
# Upload: get a URL, then PUT the raw file to it
url=$(curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/files/upload-url" \
  -H "Authorization: Bearer $BOAT_API_KEY" -H "Content-Type: application/json" \
  -d '{"path":"data/dataset.parquet"}' | jq -r .url)
curl -sS -X PUT --data-binary @dataset.parquet "$url"

# Download: get a URL, then GET it
url=$(curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/files/download-url" \
  -H "Authorization: Bearer $BOAT_API_KEY" -H "Content-Type: application/json" \
  -d '{"path":"output/model.bin"}' | jq -r .url)
curl -sS -o model.bin "$url"
```

```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
const up = await sandbox.createUploadUrl({ sandboxId: "bx_f7k2q9hd", path: "data/dataset.parquet" });
await fetch(up.url, { method: "PUT", body: await fs.readFile("dataset.parquet") });

const down = await sandbox.createDownloadUrl({ sandboxId: "bx_f7k2q9hd", path: "output/model.bin" });
const bytes = await (await fetch(down.url)).arrayBuffer();
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
import requests
from boat_sdk.models.file_url_request import FileUrlRequest

up = sandbox.create_upload_url("bx_f7k2q9hd", FileUrlRequest(path="data/dataset.parquet"))
with open("dataset.parquet", "rb") as f:
    requests.put(up.url, data=f)

down = sandbox.create_download_url("bx_f7k2q9hd", FileUrlRequest(path="output/model.bin"))
open("model.bin", "wb").write(requests.get(down.url).content)
```

* A URL works for one path and one direction (download or upload).
* It expires after 15 minutes. Pass `ttlSeconds` (up to 3600) to change that.
* An upload creates missing directories. It replaces an existing file only when the upload completes.
* Anyone who has the URL can use it until it expires. Do not log it or share it.
* Getting a download URL needs `file.read`. Getting an upload URL needs `file.write`.

For all `scp` options, read [CLI reference](https://docs.boat.dev/cli-reference.md#boat-scp).

## Related

* [VS Code, Cursor and SSH config](https://docs.boat.dev/ssh-access/editors.md)
* [Public URLs](https://docs.boat.dev/hosting)
* [Long-running tasks](https://docs.boat.dev/long-running-tasks.md)
* [Desktop streaming](https://docs.boat.dev/desktop-streaming)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.