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

# Quickstart

> From zero to a running sandbox in about five minutes

By the end of this page you'll have an API key, a cloud sandbox you can SSH into, a persistent workspace mounted inside it, and the same flow running from the SDK. Five minutes, mostly waiting on `npm install`.

## 1. Get an API key

Create an account at [runtools.ai](https://runtools.ai), then open **Dashboard → Credentials → API Keys** and create one for development. Drop it in your shell:

```bash theme={null}
export RUNTOOLS_API_KEY=rt_live_xxx
```

<Warning>
  API keys are secrets — they act as you. Keep them server-side and out of source control.
</Warning>

## 2. Install the CLI

```bash theme={null}
npm install -g @runtools-ai/cli
runtools --help
```

That's it — `runtools` is on npm. (Prefer not to install globally? `npx @runtools-ai/cli --help` works too.)

## 3. Sign in

```bash theme={null}
runtools login                          # interactive browser sign-in
runtools auth set-key "$RUNTOOLS_API_KEY"   # or store a key for scripts + CI
```

Confirm who you are:

```bash theme={null}
runtools auth whoami
```

## 4. Launch a sandbox

A sandbox is a real Firecracker microVM — your own Linux box in the cloud.

```bash theme={null}
runtools sandbox create --name my-first-sandbox --template base-ubuntu
runtools sandbox list
```

`create` returns as soon as the control plane accepts the VM; SSH comes up a moment later. Check on it, then run something inside:

```bash theme={null}
runtools sandbox get my-first-sandbox
runtools sandbox exec my-first-sandbox "echo Hello from Runtools"
```

Want a shell? Register a key and SSH straight in:

```bash theme={null}
runtools ssh-key add my-laptop --file ~/.ssh/id_ed25519.pub
runtools sandbox ssh my-first-sandbox
```

## 5. Give agents a memory

Sandboxes are ephemeral; **workspaces** are not. Mount one and an agent gets a persistent filesystem that survives across runs — its long-term memory.

```bash theme={null}
curl -X POST https://api.runtools.ai/v1/workspaces \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Project","slug":"my-project"}'
```

Mount the returned `data.id` at `/workspace` when you create a sandbox:

```bash theme={null}
runtools sandbox create \
  --name my-agent-sandbox \
  --template base-ubuntu \
  --mount 9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e:/workspace
```

Anything written to `/workspace` is still there next run.

## 6. Do it from the SDK

Same platform, typed:

```bash theme={null}
npm install @runtools-ai/sdk
```

```typescript theme={null}
import { RunTools } from '@runtools-ai/sdk';

const rt = new RunTools({ apiKey: process.env.RUNTOOLS_API_KEY });

const sandbox = await rt.sandbox.create({ name: 'sdk-demo', template: 'base-ubuntu' });
await sandbox.waitForReady();

const result = await sandbox.exec('pwd && ls -la', { cwd: '/workspace' });
console.log(result.stdout);

await sandbox.destroy();
```

## 7. Expose a dev server

Start something in the sandbox and ask for its public URL. The URL is capability-protected and shaped like `https://{port}-{sandboxId}.sandboxes.runtools.ai`:

```bash theme={null}
runtools sandbox exec my-first-sandbox "nohup python3 -m http.server 3000 --bind 0.0.0.0 >/tmp/http.log 2>&1 &"
runtools sandbox url my-first-sandbox --port 3000 --open
```

## 8. Pause or clean up

Pause to stop paying for compute while keeping the environment for later; destroy when you're done:

```bash theme={null}
runtools sandbox pause my-first-sandbox      # resume later with `sandbox resume`
runtools sandbox destroy my-first-sandbox --force
```

## Where to next

<CardGroup cols={2}>
  <Card title="Product Apps" icon="cube" href="/product-apps">
    Build a product where each end user connects their own integrations.
  </Card>

  <Card title="Hosted Connect" icon="plug" href="/sdk/hosted-connect">
    Create connect sessions, run agents, and execute tools with end-user scope.
  </Card>

  <Card title="Sandboxes" icon="server" href="/features/sandboxes">
    Lifecycle, SSH, dev URLs, mounts, and monitoring.
  </Card>

  <Card title="Agents" icon="robot" href="/features/agents">
    Define agents and put them to work.
  </Card>

  <Card title="Build a tool" icon="screwdriver-wrench" href="/sdk/custom-tools">
    Turn any API into a hosted tool with `defineTool()`.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/cli/overview">
    Every command, with flags.
  </Card>
</CardGroup>