> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zode.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install the zode CLI, make a sandbox, run a command in it, fork it, then do the same from TypeScript or curl.

You need a Zode account and a Linux or macOS machine (amd64 or arm64).

> [!NOTE]
>
> Your Personal workspace starts with $10 of free credit, no card needed: about 440 hours of a `small` sandbox. When it runs out, sandboxes stop until you add a card in **Billing**. A team workspace starts with $0 and gets its \$10 when its first card is saved. See [Pricing](https://docs.zode.dev/pricing.md#when-credit-runs-out).

## With the CLI

**1. Install the CLI**

```bash theme={null}
curl -fsSL https://zode.dev/install | sh
```

The script checks the SHA-256 of the download and installs `zode` to `/usr/local/bin` if it can write there, otherwise to `~/.local/bin`. Set `ZODE_INSTALL_DIR` to choose another directory.

**2. Sign in**

```bash theme={null}
zode login
```

`zode login` opens your browser and prints a code. Confirm the code in the browser, and the CLI saves an API key for that workspace. `zode whoami` shows who and where you are signed in.

**3. Make a sandbox**

```bash theme={null}
zode new demo
```

Without `--size` you get a `small` sandbox: 2 vCPU, 4 GB RAM, 50 GB disk. The command returns once the sandbox is running and prints its size, region and how long the create took.

**4. Run a command**

```bash theme={null}
zode exec demo -- uname -a
```

`zode exec` streams the output and exits with the command's exit code.

**5. Open a shell**

```bash theme={null}
zode ssh demo
```

You get a login shell in the sandbox. Type `exit` to leave; the sandbox keeps running.

**6. Fork it**

```bash theme={null}
zode fork demo demo-2
```

`demo-2` is a new running sandbox with a copy of `demo`'s memory and disk. Processes running in `demo` are running in `demo-2` too.

**7. Stop one, delete the other**

```bash theme={null}
zode stop demo
zode rm demo-2
```

`zode stop` hibernates `demo`: its disk and memory are kept and compute billing stops. `zode start demo` wakes it. `zode rm` deletes `demo-2` and its disk for good.

> [!NOTE]
>
> The Free plan runs at most 2 sandboxes at once. After the fork step, `demo` and `demo-2` use both slots. A third create, fork or start fails with "Your free plan runs at most 2 sandboxes at once. Stop one first." Stopped sandboxes do not count.

## From TypeScript or curl

Both need an API key. Create one in the console under **API keys** ([console.zode.dev/tokens](https://console.zode.dev/tokens)), then export it:

```bash theme={null}
export ZODE_API_KEY=zode_tok_...
```

The TypeScript SDK needs Node 22 or later:

```bash theme={null}
npm i @zodedev/sdk
```

These examples do the same steps as the CLI. If `demo` from the CLI steps still exists, run `zode rm demo` first or pick another name: names do not have to be unique, but the CLI then asks you for the id.

```ts TypeScript theme={null}
import { Sandbox } from "@zodedev/sdk";

// Reads ZODE_API_KEY from the environment.
const sbx = await Sandbox.create({ name: "demo", vcpus: 2 });

const r = await sbx.exec("uname -a");
console.log(r.exit_code, r.stdout);

const copy = await sbx.fork({ name: "demo-2" });
await sbx.stop();
await copy.delete();
```

```bash curl theme={null}
API=https://api.zode.dev
AUTH="Authorization: Bearer $ZODE_API_KEY"

# Create: returns the sandbox once it is running
ID=$(curl -sS -X POST $API/v1/sandboxes -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"name":"demo","vcpus":2}' | jq -r .id)

# Run a command: returns exit_code, stdout, stderr and duration_ms
curl -sS -X POST $API/v1/sandboxes/$ID/exec -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"command":"uname -a"}'

# Fork, stop the parent, delete the fork
FORK=$(curl -sS -X POST $API/v1/sandboxes/$ID/fork -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"name":"demo-2"}' | jq -r .id)
curl -sS -X POST $API/v1/sandboxes/$ID/stop -H "$AUTH"
curl -sS -X DELETE $API/v1/sandboxes/$FORK -H "$AUTH"
```

In the API and SDK you pick a size by `vcpus`: 2, 4, 8 or 16. RAM and disk follow the size, and leaving `vcpus` out gives `small`. A string command runs under `bash -lc`. The buffered exec route stops a command after 30 seconds by default and 55 seconds at most; for longer or interactive work, see [Sandboxes](https://docs.zode.dev/concepts/sandboxes.md#exec-and-attach).

Errors come back as JSON with a stable code, for example:

```json theme={null}
{"error": {"code": "concurrency_limit", "message": "Your free plan runs at most 2 sandboxes at once. Stop one first."}}
```

## Next

* [Sandboxes](https://docs.zode.dev/concepts/sandboxes.md): lifecycle, statuses, limits and billing.
* [Snapshots and fork](https://docs.zode.dev/concepts/snapshots-and-fork.md): copy a sandbox or roll it back.
* [CLI overview](https://docs.zode.dev/cli/overview.md) and [TypeScript SDK](https://docs.zode.dev/sdk/overview.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.