# Use a sandbox over SSH

> How to open a shell on a sandbox, copy files with scp or rsync, connect an editor, and use sandboxes with only ssh installed.

This guide shows how to use a sandbox with `ssh`: with `div` installed, or with `ssh` alone.

## Open a shell with div

```bash
div sandbox ssh $SB
```

You get a root shell on the sandbox. To run one command instead:

```bash
div sandbox ssh $SB -- tail -f /root/app/server.log
```

The session is encrypted end to end. While it is open, the sandbox is not stopped as idle. See [`div sandbox ssh`](https://docs.divergentlabs.xyz/sandboxes/cli/sandbox.md#ssh) for details.

## Connect scp, rsync or an editor

1. Run `div sandbox ssh` once for the sandbox. This authorizes your `div` SSH key on it.

   ```bash
   div sandbox ssh sb-4c1e9a -- true
   ```

2. Add the sandbox to `~/.ssh/config`:

   ```text
   Host sb-4c1e9a
     User root
     IdentityFile ~/.config/divergent/ssh_ed25519
     ProxyCommand div sandbox proxy %n
     StrictHostKeyChecking no
     UserKnownHostsFile /dev/null
   ```

3. Use the sandbox name as the host:

   ```bash
   scp ./app.py sb-4c1e9a:/root/app.py
   rsync -a ./src/ sb-4c1e9a:/root/src/
   ```

   In VS Code or another editor with remote SSH, connect to `sb-4c1e9a`.

If you want every sandbox in one entry, use `Host sb-*`.

## Use sandboxes with only ssh

`ssh div.io` gives you a prompt that creates and manages sandboxes. You need no other software, and your SSH key is your account.

### Sign up

1. Connect:

   ```bash
   ssh div.io
   ```

   The first time you connect with a new key, a short tour explains sandboxes and pricing. Press Enter to go forward, `b` to go back, or `s` to skip to sign-up.

2. Enter your email address when asked. You receive an email with a link, and your terminal shows a code.

3. Open the link and enter the code from your terminal. If the address already has an account, the link also asks you to sign in to the dashboard. The prompt continues when the key is approved.

4. Choose a plan. A new account starts with no credit, and the prompt prints a Checkout link to subscribe to Personal, $20 a month with $20 of sandbox usage included. Run `plan` to compare plans, `plan <name>` for a link to another one, or `credit add` to pay as you go instead. Paying also saves your card, and the first card saved for an org adds $1.00 of credit. The prompt tells you when the plan or the credit arrives.

`ssh` signs in with the first key it offers. To use a different key, pass it with `-i`.

An account created over SSH has no password. To sign in to the dashboard, enter your email address on the sign-in page and open the link it sends you, or run `browser` at the prompt and open the link it prints.

### Create a sandbox and open a shell

1. At the prompt, create a sandbox:

   ```text
   new --name agent-box
   ```

   The prompt opens a shell on it. Type `exit` to return to the prompt.

2. To open a shell on it again later, use the sandbox's name as the username:

   ```bash
   ssh agent-box@div.io
   ```

3. Run a command, or copy files, the same way:

   ```bash
   ssh agent-box@div.io 'cd app && npm test'
   scp ./app.py agent-box@div.io:/root/app.py
   sftp agent-box@div.io
   ```

Commands run as root. `ssh` exits with the command's exit code. The sandbox can be in any org you belong to. If the username is not a sandbox name, you get the prompt.

If the sandbox is stopped and you have a terminal, `ssh` asks whether to resume it. Without a terminal, as with `scp`, `sftp` and piped commands, it exits 1. Resume the sandbox first with `resume agent-box`.

Sessions through `div.io` are not end-to-end encrypted. If you need end-to-end encryption, use `div sandbox ssh`.

### Script the prompt

Pass a command after the host to run it without the prompt:

```bash
ssh div.io new --name agent-box --json
ssh div.io ls
```

For every command, see [ssh div.io](https://docs.divergentlabs.xyz/sandboxes/cli/ssh-prompt.md).

## Keep a long session open

- If an idle shell disconnects, add `ServerAliveInterval 60` for the host in `~/.ssh/config`.
- A session can also end when we update our servers. The sandbox and its processes keep running. Start long jobs with `nohup`, or in `tmux` (`apt-get install -y tmux`), and reconnect.