Code

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

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.

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

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

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

Code Runs preserve multiple output channels.

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 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

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 for how runtime is metered.

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

• TypeScript SDK Code - run Code snippets from the SDK.
• Code API reference - request and response shapes.
• Artifacts - persist generated outputs.
• Commands - run processes and servers.