# How to SSH into a cloud sandbox

Run `runtime sandboxes ssh <id>`. The CLI creates a key, sends only its public half and logs you in as the sandbox user.

**On Runtime, SSH needs no open port, no key upload and no bastion host.** The
login runs over one WebSocket through Runtime's API. The API authenticates it
with your key. A sandbox opens no port to the internet, and only a key that may
run commands in the sandbox can connect. You log in to a Firecracker microVM
with its own kernel, `sudo`, Python 3.12, Node.js 24 and git.

## Log in

```bash no-run
runtime sandboxes ssh <id>                  # a shell
runtime sandboxes ssh <id> -- make test     # one command; exits with its code
```

`<id>` is the sandbox's id or its name. To run the command without installing
the CLI, use `npx withruntime sandboxes ssh <id>`. The first time, the CLI
creates an SSH key for this machine in `~/.config/runtime-cloud/ssh`. It sends
only the public half, in the one login it opens. You log in as `runtime`, the
user that commands run as. You get the same environment, the proxy settings and
passwordless `sudo`.

A sandbox whose image has no SSH server, such as a custom image, gets one.
`runtime sandboxes ssh` installs `openssh-server` once. It prints a message
before it does so.

## Plain ssh, scp and rsync

Write the SSH config entry once:

```bash no-run
runtime sandboxes ssh config --install
ssh web.runtime
scp app.tar web.runtime:
rsync -a ./src/ web.runtime:/workspace/src/
```

Any tool that uses OpenSSH can then reach every sandbox as the host `<id>.runtime`
or `<name>.runtime`. `runtime sandboxes ssh config` without `--install` prints
the entry to paste yourself. Its `ProxyCommand` is `runtime sandboxes ssh proxy <id>`.
The entry turns off host key checks on purpose. Each login gets a new host key.
The connection already goes to the sandbox you named, through Runtime's
authenticated API.

## A sandbox to come back to

Give the sandbox a name and an idle pause. The same machine is available
tomorrow with its files, memory and running processes:

```bash no-run
runtime sandboxes create --name dev --get-or-create --idle-pause 900
runtime sandboxes ssh dev
```

Connecting to a paused sandbox wakes it, as any command does. The login takes a
moment longer.

## Limits

| Limit                                          | Value                                        |
| ---------------------------------------------- | -------------------------------------------- |
| Logins and port forwards open at the same time | 16 per organization                          |
| Longest session                                | 24 hours; open it again to continue          |
| Paused sandbox                                 | Woken by the login                           |
| Who can connect                                | A key allowed to run commands in the sandbox |
| User                                           | `runtime` (uid 1000), `HOME` is `/workspace` |

## Mistakes and how Runtime handles them

- **The session ends at a time limit.** An open login keeps a sandbox running.
  There is no time limit by default, as long as you have credit or free usage.
  A sandbox created with `--timeout` still ends the login at that limit. Leave
  the timeout out, or extend the limit (`runtime sandboxes extend <id> 3600`).
- **Looking for an address to SSH to.** There is none, by design. Use
  `runtime sandboxes ssh`, or the `<id>.runtime` host after
  `ssh config --install`.
- **A read-only key.** A read-only key cannot run commands, so it cannot log in
  either ([read-only keys](/docs/security#read-only-keys-and-daily-limits)).
- **Starting a server from the SSH shell and logging out.** Start servers that
  must keep running with `runtime sandboxes spawn <id> -- <command>`. The
  process keeps running after the session ends.
- **Host key warnings from other tools.** The `*.runtime` entry turns host key
  checks off for these hosts only, because every login has a new host key.

## SSH or a command from code?

SSH is for a person at a terminal. An agent or script works better with
`sbx.exec(...)` from the SDKs or `runtime sandboxes exec`. These return the exit
code and output as data. For a terminal without SSH, use
`runtime sandboxes shell <id>` ([the CLI](/docs/cli#sandboxes)).

For editors, see [VS Code Remote-SSH](/how-to/use-vs-code-remote-ssh) and
[JetBrains Gateway](/how-to/use-jetbrains-gateway). To reach a port in the
sandbox from your machine, see
[port-forward a database](/how-to/port-forward-a-database).

## Start

```bash no-run
npx withruntime sandboxes run --keep -- true
```

`--keep` leaves the sandbox running and prints how to run more. New accounts
get 100 free hours of a 1 GB machine in its first 30 days, with no card required. The first run
prints a link to approve in your browser.

Facts on this page were checked on 26 October 2026.