# 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](https://app.superhq.ai), 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:

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

```bash
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

```bash
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](https://nanite.run/docs/exec.md) has the format, and the WebSocket form for interactive shells.

## 4. Write and read a file

```bash
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:

```bash
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:

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

## 6. Clean up

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

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

## Next

- [Checkpoints](https://nanite.run/docs/checkpoints.md) to save a good state and roll back to it.
- [Environment and secrets](https://nanite.run/docs/environment-and-secrets.md) to hand an agent API keys it never sees.
- [Errors](https://nanite.run/docs/errors.md) for what each refusal means.