divergent/docs
Sandboxes

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

div sandbox ssh $SB

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

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 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.

    div sandbox ssh sb-4c1e9a -- true

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

    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:

    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:

    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:

    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:

    ssh agent-box@div.io

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

    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:

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

For every command, see ssh div.io.

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.
esc