# Code (/docs/concepts/code)



Code lets you execute interpreter-style snippets inside a live
[Sandbox](/docs/concepts/sandboxes). Use it when you want notebook-style
state, rich outputs, or streamed interpreter events. Use
[Commands](/docs/concepts/commands) when you need a top-level process
record, shell command, server process, or command log history.

## Code Contexts [#code-contexts]

A Code Context is language-specific interpreter state inside one Sandbox.
It belongs to exactly one Sandbox, has a public `cctx_` id, and keeps values
and imports alive across Code Runs while the Sandbox is live.

Provider context ids are internal. You work with CrowNest Code Context
ids and the Sandbox id that owns them.

```ts
const context = await sandbox.code.createContext({ language: "python" });
await sandbox.code.run({ contextId: context.id, code: "value = 42" });
await sandbox.code.run({ contextId: context.id, code: "print(value)" });
```

When you run code without a `contextId`, CrowNest creates or reuses a
default Code Context for the Sandbox and language. The result returns the
actual `contextId` so you can keep using or delete it.

## Code Runs [#code-runs]

A Code Run is a non-persisted interpreter execution request against a Code
Context. It returns stdout, stderr, rich outputs, execution count, and an
optional execution error. It is not a durable resource and does not create a
Command record.

Code Run results can still lead to durable data:

* Write files into the Workspace during the run.
* Export Workspace files as Artifacts.
* Use `artifactPolicy: "promote"` so CrowNest promotes eligible rich
  outputs to Artifacts.

## Languages [#languages]

CrowNest supports `python`, `javascript`, and `typescript` Code Runs. SDK
helpers default to Python; REST requests require the `language` field.
Code Contexts are language-specific, so do not reuse a Python context for a
JavaScript or TypeScript run.

## Outputs [#outputs]

Code Runs preserve multiple output channels.

| Channel      | Meaning                                                                |
| ------------ | ---------------------------------------------------------------------- |
| `stdout`     | Captured stdout as a string.                                           |
| `stderr`     | Captured stderr as a string.                                           |
| `outputs`    | Structured inline, Artifact, or rejected rich outputs.                 |
| `error`      | Interpreter error with message, optional name, and optional traceback. |
| `durationMs` | Runtime duration when available.                                       |

Inline outputs cover small text, markdown, JSON, data, charts, and LaTeX.
Artifact outputs cover promoted formats such as PNG, JPEG, SVG, HTML,
JSON, chart, and data. Rejected outputs include the format and reason, such
as `output_too_large`, `requires_artifact_promotion`, or
`unsupported_format`.

## Streaming [#streaming]

Streaming Code Runs emit server-sent events for live `stdout` and `stderr`
chunks, plus `output`, `error`, and `complete`. The final `complete` event
carries the same `RunCodeResult` shape as a blocking Code Run, with
`stdout` and `stderr` joined into strings.

Code Run streams are not Command log streams. They do not assign event ids
or support `Last-Event-ID` resume in v1. If a completed idempotency key is
replayed, CrowNest emits a single `complete` event with the stored result.

## Limits and timeouts [#limits-and-timeouts]

Code source, run duration, context creation, streamed data, and inline
outputs are capped by API validation. CrowNest promotes eligible large
outputs to Artifacts when requested and rejects unsupported outputs instead
of inlining them.

Run timeouts and stream disconnects bound the CrowNest request or iterator.
The current Cloudflare provider can continue the underlying kernel execution
briefly afterward. Delete the Code Context, or destroy its Sandbox, when hard
termination is required.

File and Artifact storage limits, Sandbox TTLs, and plan quotas still
apply. See [usage and billing](/docs/concepts/usage-and-billing) for how
runtime is metered.

## Errors [#errors]

Interpreter errors are execution results, not API transport failures. A
Python exception can return `200` from the API while the result contains
`error.message` and optional traceback details. API failures use the normal
CrowNest error envelope and SDK exceptions: `forbidden`, `not_found`,
`sandbox_destroyed`, `unsupported_code_language`, `code_source_too_large`,
and `quota_exceeded` are examples.

## Next steps [#next-steps]

* [TypeScript SDK Code](/docs/sdk/code) - run Code snippets from the SDK.
* [Code API reference](/docs/api/code) - request and response shapes.
* [Artifacts](/docs/concepts/artifacts) - persist generated outputs.
* [Commands](/docs/concepts/commands) - run processes and servers.