TypeScript SDK

The @crownest/sdk package is the official TypeScript client for CrowNest. It wraps the REST API with typed resource clients for sandboxes, commands, files, artifacts, previews, and projects, and returns a convenient SandboxHandle that binds helpers to a specific sandbox.

Install

Add the package to your project with your package manager of choice.

pnpm add @crownest/sdk
# or
npm install @crownest/sdk
# or
yarn add @crownest/sdk

Create a client

Call createCrowNestClient to construct a client. All options are optional.

import { createCrowNestClient } from "@crownest/sdk";

const client = createCrowNestClient({
  apiKey: "cn_live_...", // falls back to env CROWNEST_API_KEY
  baseUrl: "https://api.crownest.dev", // default
});

Create API keys in the dashboard; the raw key value is shown once at creation.

SandboxHandle

client.sandboxes.create() and client.sandboxes.get() return a SandboxHandle: the full Sandbox object (id, status, expiresAt, metadata, and so on) plus helpers bound to that sandbox, so you don't pass the sandbox ID on every call.

const sandbox = await client.sandboxes.create({ template: "python" });

const result = await sandbox.commands.run("python -c 'print(40 + 2)'");
console.log(result.exitCode, result.stdout);

await sandbox.files.write("notes.txt", "hello from crownest");
const artifact = await sandbox.artifacts.create({ path: "notes.txt" });

await sandbox.kill();

The handle exposes:

• sandbox.commands.run, sandbox.commands.start, sandbox.commands.cancel
• sandbox.files.read, write, delete, list, stat, mkdir, move, downloadUrl
• sandbox.artifacts.create, sandbox.artifacts.list
• sandbox.previews.create, sandbox.previews.list
• sandbox.kill() — destroys the sandbox and returns an updated handle

For operations that target a resource by ID rather than a sandbox (for example commands.get or artifacts.download), use the top-level clients on client.

Projects

List the projects your API key can access.

const projects = await client.projects.list();
// [{ id: "prj_...", orgId, name, createdAt }, ...]

list() returns Promise<readonly Project[]>.

Exported types

The package exports CrowNestClientOptions, RunCommandOptions, SandboxHandle, and the CrowNestApiError class, plus the resource types (Sandbox, Command, Artifact, Preview, Project, and friends) from the contracts package.

Resource clients

Each resource client has its own reference page:

• Sandboxes — client.sandboxes: create, get, list, kill.
• Commands — client.commands: run, start, get, cancel, logs, streamLogs.
• Files — client.files: read, write, delete, list, stat, mkdir, move, downloadUrl.
• Artifacts — client.artifacts: create, list, get, download, downloadUrl, delete.
• Previews — client.previews: create, list, get, revoke.
• Errors — CrowNestApiError, error codes, and retry guidance.

Next steps

• Sandboxes — create your first sandbox.
• Errors — handle failures and retries.
• Sandboxes concept — lifecycle, TTL, and templates.