CrowNest Docs

Drive CrowNest sandboxes from your terminal with the crownest CLI — create a sandbox, run commands, move files, export artifacts, and stream logs.

This quickstart walks you through the full sandbox lifecycle from your terminal: log in, create a sandbox, run a command, move files in and out, export an artifact, expose a preview, stream logs, and clean up.

Prerequisites

You need two things before you start.

Node.js 18 or later, to install the @crownest/cli package.
A CrowNest API key, created in the dashboard at https://crownest.dev. See API keys for scopes and presets.

[!WARNING] The raw API key is shown once, at creation time. Copy it immediately and store it somewhere safe — you can't view it again later.

Install and log in

Install the CLI globally, then save your credentials.

Install the package. It provides the crownest binary.
Terminal
```
pnpm add -g @crownest/cli
```
Log in with your API key. This saves credentials to ~/.crownest/config.json (or under $XDG_CONFIG_HOME when set; override the location with CROWNEST_CONFIG_PATH).
Terminal
```
crownest login --api-key cn_live_...
```
Running crownest login without --api-key prints guidance instead. You can also skip the config file entirely and set CROWNEST_API_KEY in the environment. CROWNEST_API_URL overrides the API endpoint (default https://api.crownest.dev).

Walk through the lifecycle

Each step uses the sandbox ID printed in step 1; substitute your own.

Create a sandbox. The command prints the new sandbox ID.
Terminal
```
crownest sandboxes create --template python
```
Output
```
sbx_a1b2c3d4
```
Use --project <prj_id> to create the sandbox in a specific project. crownest sandboxes list returns your live sandboxes as JSON.
Run a command with exec. Everything after -- runs inside the sandbox, and the CLI prints the finished command record as JSON.
Terminal
```
crownest exec sbx_a1b2c3d4 -- python -c 'print(40 + 2)'
```
The JSON output includes the command's id, status, exitCode, stdout, and stderr. crownest exec is an alias of crownest commands run.

[!IMPORTANT] The CLI's own exit code reports whether execution succeeded: 0 for success, 1 for errors, and 2 for usage errors. A command that runs to completion with a non-zero exit code still exits 0 — inspect exitCode in the JSON output to check whether your command failed.
Upload and read files. All paths are inside /workspace, the sandbox's working filesystem area.
Terminal
```
crownest files upload sbx_a1b2c3d4 ./data.csv --to data.csv
crownest files write sbx_a1b2c3d4 notes.txt "hello from crownest"
crownest files read sbx_a1b2c3d4 notes.txt
```
Output
```
hello from crownest
```
files read writes the raw file content to stdout, so you can pipe it. Related commands: files list, files stat, files mkdir, files move, and files delete — see the CLI reference.
Export an artifact. The workspace disappears with the sandbox, so copy anything you want to keep to durable storage. The command prints the artifact ID.
Terminal
```
crownest artifacts create sbx_a1b2c3d4 notes.txt --name notes
```
Output
```
art_e5f6g7h8
```
Download it later — even after the sandbox is gone — with crownest artifacts download art_e5f6g7h8 --output ./notes.txt.
Expose a preview. Start an HTTP server in the background with commands start, then create a preview for its port. The command prints the authenticated preview URL.
Terminal
```
crownest commands start sbx_a1b2c3d4 -- python -m http.server 8000
crownest previews create sbx_a1b2c3d4 --port 8000
```
Output
```
https://p-a1b2c3.preview.crownest.dev
```
Previews require authentication in v1; see Previews. Revoke one with crownest previews revoke <preview-id>.
Stream logs. crownest logs follows a command's output live until it reaches a terminal state — useful with long-running commands launched by commands start. The JSON printed by exec and commands start includes the command ID.
Terminal
```
crownest logs cmd_i9j0k1l2
```
You can also scope by sandbox: crownest logs sbx_a1b2c3d4 --command cmd_i9j0k1l2. Cancel a running command with crownest commands cancel cmd_i9j0k1l2 (add --force to skip graceful shutdown).
Kill the sandbox. This stops billing and releases the environment. The command prints the sandbox ID and its new status.
Terminal
```
crownest sandboxes kill sbx_a1b2c3d4
```
Output
```
sbx_a1b2c3d4 destroyed
```
Sandboxes also expire automatically at their TTL — see Sandboxes.

Next steps

Browse every command and flag in the CLI reference.
Learn how lifetimes, templates, and statuses work in Sandboxes.
Understand log streaming and collection in Commands.
Build programmatically with the TypeScript SDK quickstart or the Python SDK quickstart.

CLI quickstart

Prerequisites

Install and log in

Walk through the lifecycle

Next steps

On this page