# Quickstart (https://luxor.ai/docs/sandbox/quickstart)

> For the complete documentation index, see [llms.txt](https://luxor.ai/llms.txt)

Spin up your first Sandbox session in under a minute. Install the CLI or SDK, authenticate with an API key, and run commands inside an isolated Linux VM.

Sandbox gives you disposable full Linux VMs you can drive from the CLI or the Go, TypeScript, and Python SDKs. This guide takes you from install to a running sandbox in a few minutes. Pick your tool in the first code block and the selection follows you down the page.

## 1. Install

### Supported platforms

The `luxor` CLI supports Linux x86-64 (`linux/amd64`) and Apple silicon macOS (`darwin/arm64`); Intel macOS is
not supported.

**CLI**
```bash
curl -fsSL https://tenki.cloud/install.sh | bash
```

Pin a version with `bash -s -- --version <x>` or change the location with `TENKI_INSTALL_DIR`. See the [CLI Reference](https://luxor.ai/docs/sandbox/cli.md) for more.

**TypeScript**
```bash
npm install @tenkicloud/sandbox
```

**Go**
```bash
go get github.com/LuxorLabs/tenki-sdk-go/sandbox
```

**Python**
Requires Python 3.10+.

```bash
pip install tenki
```

## 2. Authenticate

Sign the CLI in interactively. For SDKs and automation, Sandbox onboarding creates an initial API key. Export it
as `TENKI_API_KEY`. See [Manage API keys](https://luxor.ai/docs/account/api-keys.md) to create additional keys, choose an
expiration date, rotate keys, or revoke them.

**CLI**
```bash
# Opens your browser to sign in and choose a workspace
luxor login

# Confirm you are signed in
luxor status
```

Browser sign-in creates a 30-day API key bound to the workspace you choose and stores it in the CLI. Sandbox
commands infer their workspace from that credential.

Prefer an existing key? Run `luxor login --api-key tk_your_api_key`. See
[Authentication](https://luxor.ai/docs/sandbox/cli.md#authentication) for headless and CI options.

**TypeScript**
```bash
export TENKI_API_KEY=tk_your_api_key
```

**Go**
```bash
export TENKI_API_KEY=tk_your_api_key
```

**Python**
```bash
export TENKI_API_KEY=tk_your_api_key
```

## 3. Create a sandbox and run a command

Create a session, run a command inside it, and read the output back. The session is a fresh Linux VM, isolated from your machine.

**CLI**
```bash
# Create a session (waits for RUNNING and prints the session ID)
luxor sandbox create --name demo

# Make it your current session so later commands can omit --session
luxor sandbox set <session-id>

# Run a command inside it
luxor sandbox exec -c 'uname -a && whoami'

# Tear it down
luxor sandbox terminate
```

**TypeScript**
```typescript
// sandbox.ts
import { stdoutText, TenkiSandbox } from "@tenkicloud/sandbox";

const sandbox = new TenkiSandbox(); // reads TENKI_API_KEY from env

await using session = await sandbox.createAndWait({ name: "demo" });

const result = await session.exec("bash", { args: ["-lc", "uname -a && whoami"] });
console.log(`exit=${result.exitCode}\n${stdoutText(result)}`);
// `await using` closes the session when it leaves scope.
```

Run it:

```bash
npx tsx sandbox.ts
```

**Go**
```go
// main.go
package main

import (
  "context"
  "log"
  "time"

  tenkisandbox "github.com/LuxorLabs/tenki-sdk-go/sandbox"
)

func main() {
  ctx := context.Background()

  client, err := tenkisandbox.New() // reads TENKI_API_KEY from env
  if err != nil {
    log.Fatal(err)
  }
  defer client.Close()

  session, err := client.CreateAndWait(ctx, 3*time.Minute, tenkisandbox.WithName("demo"))
  if err != nil {
    log.Fatal(err)
  }
  defer session.Close(ctx) // tears the session down on return

  result, err := session.Exec(ctx, "bash", tenkisandbox.WithArgs("-lc", "uname -a && whoami"))
  if err != nil {
    log.Fatal(err)
  }
  log.Printf("exit=%d\n%s", result.ExitCode, result.StdoutString())
}
```

Run it:

```bash
go run main.go
```

**Python**
```python
# sandbox.py
from tenki import Sandbox

# Reads TENKI_API_KEY from env. Waits for RUNNING; closes on block exit.
with Sandbox.create(name="demo") as sb:
    result = sb.exec("bash", "-lc", "uname -a && whoami")
    print(f"exit={result.exit_code}\n{result.stdout_text}")
```

Run it:

```bash
python sandbox.py
```

You should see the guest's kernel info and username printed back. That output came from inside the VM.

## What's next

* Do more with a session: [Sessions](https://luxor.ai/docs/sandbox/sessions.md) covers command execution, file I/O, port exposure, and SSH.
* [Concepts](https://luxor.ai/docs/sandbox/concepts.md): how sessions, volumes, and snapshots fit together.
* [Recipes](https://luxor.ai/docs/sandbox/recipes.md): run an AI agent, checkpoint an environment, cache dependencies.
* [Anchor](https://luxor.ai/docs/sandbox/anchor.md): a pre-built image for browser automation through an Anchor-managed browser.
* [Chrome and Chromium](https://luxor.ai/docs/sandbox/chrome.md): run a headless or headed browser, drive it over CDP, and watch it through noVNC.
* [Grok](https://luxor.ai/docs/sandbox/grok.md): a pre-built image with xAI's Grok Build coding agent for headless `grok -p` runs.
* [Droid](https://luxor.ai/docs/sandbox/droid.md): a pre-built image with Factory's Droid coding agent for headless `droid exec` runs.
* [Amp](https://luxor.ai/docs/sandbox/amp.md): a pre-built image with Sourcegraph's Amp coding agent for headless `amp -x` runs.
* [Crabbox](https://luxor.ai/docs/sandbox/crabbox.md): keep a sandbox warm and run your test suite on it from your local checkout, like CI before you commit.
* [Harbor](https://luxor.ai/docs/sandbox/harbor.md): run agent benchmarks such as Terminal-Bench with every trial in its own sandbox.
* [Pi](https://luxor.ai/docs/sandbox/pi.md): a pre-built image with the open source Pi coding agent, provider-agnostic and run inside a per-session isolation boundary.
* [Prime Agent](https://luxor.ai/docs/sandbox/prime-agent.md): a pre-built image with Prime Intellect's Prime Agent coding and research harness, its Python kernel prewarmed, for headless `prime-agent -p` runs.
* [TinyFish](https://luxor.ai/docs/sandbox/tinyfish.md): a pre-built image with the TinyFish CLI, SDK, and Playwright client for web agents, remote browsers, fetch, and search.
* [Hotdata](https://luxor.ai/docs/sandbox/hotdata.md): a pre-built image with the Hotdata CLI, Python SDK, and agent skill, for giving an agent its own database to load files into and query with SQL.
* [Persistent Volumes](https://luxor.ai/docs/sandbox/volumes.md) and [Snapshots](https://luxor.ai/docs/sandbox/snapshots.md) for durable state.
* [CLI Reference](https://luxor.ai/docs/sandbox/cli.md) and [SDK Reference](https://luxor.ai/docs/sandbox/sdk.md) for every command and option.

Need help? Email [hello@luxor.ai](mailto:hello@luxor.ai) and we'll help you get set up.