Quickstart

1. Sign in and get a quota#

Sign in to the dashboard with GitHub or Google. A new account cannot create sandboxes yet: its quota is zero. Add a payment method on the dashboard's Billing page to subscribe, or ask us to enable your account.

2. Sign in from mat#

This guide assumes the mat binary is on your PATH. Sign in with your API's address:

$ mat login --url https://YOUR-API-ADDRESS

mat prints a code and a link. Open the link, check that the code matches, and confirm. The session lasts 7 days. Then check your account:

$ mat whoami

If sandboxes shows 0 of 0, your account has no quota yet. See step 1.

3. Create a sandbox#

mat create prints the new sandbox's ID once it is running. Keep it in a variable:

$ ID=$(mat create --size small)$ echo $IDsb-4f1c9e27a0b3d5c86e12

4. Run commands#

Everything after -- is the program and its arguments, passed as they are. For pipes, && or other shell syntax, ask for a shell:

$ mat exec $ID -- python3 -c 'print(6*7)'42$ mat exec $ID -- sh -c 'cd /workspace && git clone https://github.com/octocat/Hello-World.git && ls'$ mat exec $ID -- sudo apt-get install -y sqlite3

mat exec exits with the command's exit code. Ctrl-C interrupts the command; a second Ctrl-C detaches and leaves it running.

5. Move files#

$ mat cp ./app.py $ID:/workspace/app.py$ mat cp $ID:/workspace/out.json ./out.json

One file at a time, up to 1 GiB. A sandbox path is the ID, a colon and an absolute path.

6. Open a shell#

$ mat shell $ID

A login shell as agent. Closing the connection ends it; use tmux inside for sessions that should survive.

7. Pause and resume#

A sandbox pauses by itself after 10 idle minutes. You can also pause it now. Using it again resumes it, with its processes where they were:

$ mat pause $IDsb-4f1c9e27a0b3d5c86e12 is paused$ mat exec $ID -- uptime

8. Clean up#

Copy out anything you want to keep, then delete the sandbox. Deleting removes its files, memory and snapshots.

$ mat rm $IDsb-4f1c9e27a0b3d5c86e12 is deleted

From a program#

Programs use an API key. Create one on the dashboard's API keys page; it is shown once. Then either save it for mat:

$ mat login --url https://YOUR-API-ADDRESS --api-key

or set both variables, which mat reads before any saved sign-in:

$ export MATRYOSHKA_API_URL=https://YOUR-API-ADDRESS$ export MATRYOSHKA_API_KEY=mk_…

The same key works with the HTTP API:

$ curl -X POST "$MATRYOSHKA_API_URL/v1/sandboxes" \    -H "Authorization: Bearer $MATRYOSHKA_API_KEY" \    -H "Content-Type: application/json" \    -H "Idempotency-Key: build-1842" \    -d '{"size": "small"}'

See the API reference for every route.