Skip to main content

Run your first sandbox

In this tutorial you create a sandbox, which is a small Linux virtual machine for agents and untrusted code. You run commands in it, copy a file in and out, reach a web server inside it from your own machine, and then delete it.

Allow about 10 minutes.

Before you start​

You need three things:

  • A tritonctl binary on your PATH, signed in to your cloud. If you have not done this yet, follow steps 1 and 2 of Run your first instance.
  • A project in which your operator has turned on sandboxes.
  • curl on your workstation.

Every command below runs on your workstation.

Step 1: Check what the cloud offers​

tritonctl sandbox capability

The output lists each sandbox feature as available or refused. Exec, files, and snapshots are available on every cloud that offers sandboxes. Port tunnels are behind the ports feature gate, which is on by default. Some other features are gated too: an operator turns them on per tenant.

Step 2: Create a sandbox​

tritonctl sandbox create --name dev --package sandbox-2g --ttl 1h

The command waits until the sandbox runs. --package sandbox-2g gives it 2 vCPUs, 2 GiB of memory, and an 8 GiB disk. --ttl 1h deletes it after one hour, so nothing is left behind if you stop partway through.

List your sandboxes:

tritonctl sandbox list

You see dev in the running state.

Step 3: Run a command​

tritonctl sandbox exec dev -- uname -a

The command prints the guest's kernel line, then one summary line on stderr. The exit status of tritonctl is the exit status of the program in the sandbox.

Open an interactive shell:

tritonctl sandbox exec -t -i dev -- bash

You are now in the guest, as the user sandbox. Type exit to leave. The key sequence ~. also detaches.

Step 4: Copy a file in and out​

Make a file on your workstation and copy it into the sandbox:

echo "hello from my workstation" > hello.txt
tritonctl sandbox fs put dev ./hello.txt /work/hello.txt

Read it back from the sandbox:

tritonctl sandbox fs cat dev /work/hello.txt

You see hello from my workstation.

Make a new file in the guest, then copy it out:

tritonctl sandbox exec dev -- sh -c 'date > /work/now.txt'
tritonctl sandbox fs get dev /work/now.txt ./now.txt
cat now.txt

You see the date and time in the guest.

Step 5: Reach a web server in the sandbox​

Start a web server in the guest. Leave it running in the background:

tritonctl sandbox exec dev -- python3 -m http.server 8000 --bind 127.0.0.1 &

Forward the port to your workstation. This command stays in the foreground while the tunnel is open, so run it in a second terminal:

tritonctl sandbox port-forward dev 8000

In a third terminal, or after you send the forward to the background:

curl http://127.0.0.1:8000/

You see the HTML directory listing of the guest's working directory. The tunnel runs through the Cloud API with your own credential. The sandbox's network stays closed. Press Ctrl-C in the terminal with port-forward to close the tunnel.

Step 6: Delete the sandbox​

tritonctl sandbox delete -y dev

-y answers the confirmation prompt. Run tritonctl sandbox list again: dev is gone.

You created a sandbox, ran commands in it, moved files, reached a port, and deleted it.

Next steps​