Start

Quickstart

Make an API key, create a sandbox, run a command, move files and let it sleep, all with curl.

This walks through one sandbox from start to finish with curl. It takes a few minutes.

1. Get an API key

Sign in to the console, open API keys in your workspace and create a key. It is shown once, so copy it then. A key starts with sk_. Keep it on your server; anyone holding it can run sandboxes on your credits.

Put the base URL and the header in your shell:

shell
export API=https://api.nanite.run/v1/sandboxes
export AUTH="Authorization: Bearer sk_..."

Your organization needs credits to run sandboxes. Buy them on the Billing page of the console.

2. Create a sandbox

A sandbox has a name you choose: lowercase letters, digits and dashes.

shell
curl -X POST $API -H "$AUTH" -d '{"name": "agent-1"}'
json
{
  "id": "sbx-01jbx3w2v8k6p3m9q0t7r4n5ce",
  "name": "agent-1",
  "status": "running",
  "url_settings": { "auth": "sandbox" },
  "created_at": "2026-10-31T09:20:00.000Z",
  ...
}

The answer comes back once the machine is up, usually in under a second.

3. Run a command

shell
curl -X POST "$API/agent-1/exec?cmd=uname&cmd=-a" -H "$AUTH" --output -

Each cmd is one argument. The response streams the output as it is written, each chunk tagged with one byte that says whether it is stdout or stderr, and ends with the exit code. Exec has the format, and the WebSocket form for interactive shells.

4. Write and read a file

shell
echo "echo hello from nanite" > hello.sh
curl -X PUT "$API/agent-1/fs/write?path=/root/app/hello.sh&mkdir=true" -H "$AUTH" --data-binary @hello.sh
curl -X POST "$API/agent-1/exec?cmd=sh&cmd=/root/app/hello.sh" -H "$AUTH" --output -
curl "$API/agent-1/fs/read?path=/root/app/hello.sh" -H "$AUTH"

mkdir=true creates the parent directories. Install anything else with apt-get; it stays on the disk.

5. Let it sleep

Leave it alone for 30 seconds and the sandbox stops on its own. You can also stop it now:

shell
curl -X POST $API/agent-1/stop -H "$AUTH"
json
{ "name": "agent-1", "status": "warm", ... }

A stopped sandbox costs only its storage. The next request wakes it, with the disk as you left it:

shell
curl "$API/agent-1/fs/read?path=/root/app/hello.sh" -H "$AUTH"

6. Clean up

shell
curl -X DELETE $API/agent-1 -H "$AUTH"

Deleting removes the disk and every checkpoint of the sandbox. It cannot be undone.

Next