Run commands and move files in a sandbox

This guide runs programs in a running sandbox and moves files between your workstation and the sandbox. You need tritonctl signed in to your cloud and a sandbox in the running state. Every command runs on your workstation.

A sandbox argument is a name, a UUID, or a UUID prefix. The examples use a sandbox named dev.

Run a program

Put the program after --:

tritonctl sandbox exec dev -- make test

The exit status of tritonctl is the program's own. A program killed by a signal exits with 128 plus the signal number. tritonctl also prints one summary line on stderr. Add -q to get only the program's output.

To run a shell line instead of a program:

tritonctl sandbox exec dev --cmd 'cd /work && ls -l | head'

Set the working directory, environment variables, and a time limit:

tritonctl sandbox exec dev --cwd /work --env MODE=ci --max-duration 10m -- ./run.sh

Open an interactive shell

tritonctl sandbox exec -t -i dev -- bash

-t gives the program a terminal, and -i sends your keyboard to it. The key sequence ~. detaches. Do not use -t -i from a script.

Reattach to a long job

Give the job a tag:

tritonctl sandbox exec dev --tag build -- make all

If your terminal closes, reattach by the tag:

tritonctl sandbox exec-attach dev build

Exec records stay for the life of the sandbox.

Copy files in and out

Copy a file from your workstation into the sandbox:

tritonctl sandbox fs put dev ./data.csv /work/data.csv

Copy a file out of the sandbox:

tritonctl sandbox fs get dev /work/out.json ./out.json

An upload that is cancelled leaves the old file as it was.

Read and change files in place

Task	Command
Print a file	tritonctl sandbox fs cat dev /work/data.csv
List a directory	tritonctl sandbox fs ls dev /work
Show one path	tritonctl sandbox fs stat dev /work/data.csv
Make a directory	tritonctl sandbox fs mkdir dev /work/out
Move or rename	tritonctl sandbox fs mv dev /work/a.txt /work/b.txt
Remove	tritonctl sandbox fs rm dev /work/b.txt

fs ls prints the mode, size, modification time, and name. Add -j for JSON.

Watch a directory

tritonctl sandbox fs watch dev /work --recursive

The command prints one line per create, write, remove, rename, or mode change until you press Ctrl-C.

If a command fails

Error	Cause	Fix
409 SandboxNotRunning	The sandbox is stopped or paused.	Run tritonctl sandbox start dev or tritonctl sandbox resume dev.
Exit status 2	A prompt had no terminal.	Pass -y in scripts.
Exit status 3	The sandbox name did not match.	Check tritonctl sandbox list.

See also

• tritonctl sandbox for every flag on exec and fs.
• How sandboxes work for how commands reach the guest.
• Use the SDKs and the MCP server to do the same from Python or TypeScript.