# Introduction (/docs)



CrowNest provides safe cloud sandboxes for AI agents and developers. Each
sandbox is an isolated live execution environment where you run commands,
manage files, expose authenticated previews, preserve logs, and collect
artifacts through one API.

## Who it's for [#who-its-for]

CrowNest is built for AI application developers whose agents run code,
install packages, process files, or host preview services. It also serves
teams running many agent sessions who need org-scoped API keys, project
separation, usage visibility, and quotas.

## Core resources [#core-resources]

CrowNest's API surface is organized around a small set of resources. Each
one maps to a section of the [API reference](/docs/api/overview).

| Resource                                       | What it is                                                                             |
| ---------------------------------------------- | -------------------------------------------------------------------------------------- |
| [Sandbox](/docs/concepts/sandboxes)            | An isolated live execution environment with a requested lifetime (TTL).                |
| [Command](/docs/concepts/commands)             | A top-level process invocation record with captured logs and an exit code.             |
| [Workspace Run](/docs/concepts/workspace-runs) | An archive-based run that executes a repo command and keeps durable evidence.          |
| Workspace                                      | The working filesystem area inside a live sandbox, rooted at `/workspace`.             |
| [Artifact](/docs/concepts/artifacts)           | A durable, indexed output you explicitly export from a sandbox to object storage.      |
| [Preview](/docs/concepts/previews)             | An authenticated exposed HTTP service with a URL like `https://p-a1b2c3.crownest.dev`. |

The workspace is a descriptive term rather than a resource: every file
operation acts on paths inside `/workspace`, and the
[file APIs](/docs/concepts/files) are confined to it.

## How it fits together [#how-it-fits-together]

A typical sandbox session moves through the resources in order.

1. Create a sandbox from the `python-node` template. The sandbox moves through
   `creating` and `starting` to `ready`.
2. Run commands inside the sandbox. Each invocation becomes a command record
   with streamed logs, an exit code, and full stdout/stderr.
3. Read and write files in `/workspace` to stage inputs and inspect outputs.
4. Export important outputs as artifacts. The workspace is ephemeral, so
   only explicit exports survive the sandbox.
5. Expose a port as a preview when your code hosts an HTTP service, and
   share its authenticated URL.
6. Kill the sandbox when you're done, or let it expire at its TTL. Logs,
   artifacts, and the sandbox record persist after the environment is gone.

For repo and agent archive workflows, use a Workspace Run. You upload a `.tar.gz` archive,
run a command in `python-node`, stream stdout and stderr, collect explicit
artifacts, and read an Evidence Bundle after the sandbox is cleaned up.

<Callout type="warn" title="Important">
  Artifact export is always explicit. When a sandbox is destroyed, its filesystem is
  gone — nothing is copied out automatically.
</Callout>

## Where to go next [#where-to-go-next]

Pick the path that matches how you want to work.

* **Quickstarts** — get a sandbox running in minutes with the
  [TypeScript SDK](/docs/quickstart/sdk), the
  [Python SDK](/docs/quickstart/python), or the
  [CLI](/docs/quickstart/cli).
* **Concepts** — understand [sandboxes](/docs/concepts/sandboxes),
  [commands](/docs/concepts/commands),
  [Workspace Runs](/docs/concepts/workspace-runs), [files](/docs/concepts/files),
  [artifacts](/docs/concepts/artifacts), [previews](/docs/concepts/previews),
  [API keys](/docs/concepts/api-keys), and
  [usage and billing](/docs/concepts/usage-and-billing).
* **References** — browse the [TypeScript SDK reference](/docs/sdk), the
  [Python SDK reference](/docs/python), the [CLI reference](/docs/cli), and
  the [REST API reference](/docs/api/overview), including
  [authentication](/docs/api/authentication) and
  [error handling](/docs/api/errors).
* **Integrations** — wire CrowNest into agent stacks with the
  [MCP server](/docs/integrations/mcp) or the
  [Vercel AI SDK tools](/docs/integrations/ai-sdk).
* **Guides** — compare the product layer with a direct runtime call in
  [CrowNest vs direct Cloudflare Sandbox](/docs/guides/crownest-vs-cloudflare-sandbox).