# Capability matrix (/docs/api/capabilities) This matrix maps each CrowNest operation to the surfaces that expose it: MCP tools, CLI commands, the TypeScript SDK, and the Python SDK. A `-` means the surface does not expose that operation. ## Projects and usage [#projects-and-usage] | Resource | Operation | MCP tool | CLI command | TypeScript SDK | Python SDK | | -------- | --------- | ---------------- | ------------------------ | -------------------------- | -------------------------- | | Project | List | `list_projects` | `crownest projects list` | `client.projects.list()` | `client.projects.list()` | | Project | Create | `create_project` | - | `client.projects.create()` | `client.projects.create()` | | Usage | Read | `get_usage` | - | `client.usage()` | `client.usage()` | ## Sandboxes [#sandboxes] | Resource | Operation | MCP tool | CLI command | TypeScript SDK | Python SDK | | -------- | --------- | ----------------- | ---------------------------- | ----------------------------------------------- | ------------------------------------------------- | | Sandbox | Create | `create_sandbox` | `crownest sandboxes create` | `client.sandboxes.create()` | `client.sandboxes.create()` | | Sandbox | List | `list_sandboxes` | `crownest sandboxes list` | `client.sandboxes.list()` | `client.sandboxes.list()` | | Sandbox | Get | `get_sandbox` | `crownest sandboxes get` | `client.sandboxes.get()` | `client.sandboxes.get()` | | Sandbox | Set TTL | `set_sandbox_ttl` | `crownest sandboxes set-ttl` | `client.sandboxes.setTtl()`, `sandbox.setTtl()` | `client.sandboxes.set_ttl()`, `sandbox.set_ttl()` | | Sandbox | Kill | `kill_sandbox` | `crownest sandboxes kill` | `client.sandboxes.kill()`, `sandbox.kill()` | `client.sandboxes.kill()`, `sandbox.kill()` | MCP tools that accept `sandbox_id` can omit it to use the session's lazy default Sandbox. The first omitted `sandbox_id` call creates that Sandbox; later calls reuse it until it expires, is killed, or the MCP server exits. Passing a visible existing Sandbox ID adopts it for the session without marking it as server-created cleanup state. ## Commands [#commands] | Resource | Operation | MCP tool | CLI command | TypeScript SDK | Python SDK | | -------- | ----------------- | ---------------------------------- | ------------------------------------ | -------------------------------------------------------- | --------------------------------------------------------- | | Command | Run and wait | `run_command` | `crownest commands run` | `client.commands.run()`, `sandbox.commands.run()` | `client.commands.run()`, `sandbox.commands.run()` | | Command | Run in background | `run_command` (`background: true`) | `crownest commands run --background` | `client.commands.run(..., { background: true })` | `client.commands.run(..., background=True)` | | Command | Get | `get_command` | `crownest commands get` | `client.commands.get()` | `client.commands.get()` | | Command | Logs | `stream_command_logs` | `crownest logs` | `client.commands.logs()`, `client.commands.streamLogs()` | `client.commands.logs()`, `client.commands.stream_logs()` | | Command | Cancel | `cancel_command` | `crownest commands cancel` | `client.commands.cancel()`, `sandbox.commands.cancel()` | `client.commands.cancel()`, `sandbox.commands.cancel()` | Commands are persisted process invocation records. For interpreter state, use Code Contexts and Code Runs. ## Workspace Runs [#workspace-runs] | Resource | Operation | MCP tool | CLI command | TypeScript SDK | Python SDK | | ------------- | --------------------- | ----------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | Workspace Run | Create | `create_workspace_run` | `crownest workspace-runs create` | `client.workspaceRuns.create()` | `client.workspace_runs.create()` | | Workspace Run | Upload archive | `upload_workspace_run_archive` | `crownest workspace-runs upload` | `client.workspaceRuns.uploadArchive()` | `client.workspace_runs.upload_archive()` | | Workspace Run | Create transfer | `create_workspace_run_archive_transfer` | - | `client.workspaceRuns.createArchiveTransfer()` | `client.workspace_runs.create_archive_transfer()` | | Workspace Run | Upload transfer bytes | `upload_workspace_run_archive_transfer` | - | `client.workspaceRuns.uploadArchiveToTransfer()` | `client.workspace_runs.upload_archive_to_transfer()` | | Workspace Run | Finalize archive | `finalize_workspace_run_archive` | - | `client.workspaceRuns.finalizeArchive()` | `client.workspace_runs.finalize_archive()` | | Workspace Run | Run archive | MCP flow: create, upload, finalize, start | `crownest workspace-runs run-archive` | SDK flow: create, upload, finalize, start, stream | SDK flow: create, upload, finalize, start, stream | | Workspace Run | Start | `start_workspace_run` | `crownest workspace-runs start` | `client.workspaceRuns.start()` | `client.workspace_runs.start()` | | Workspace Run | Get status | `get_workspace_run` | `crownest workspace-runs status` | `client.workspaceRuns.get()` | `client.workspace_runs.get()` | | Workspace Run | List | `list_workspace_runs` | `crownest workspace-runs list` | `client.workspaceRuns.list()` | `client.workspace_runs.list()` | | Workspace Run | Replay events | `replay_workspace_run_events` | `crownest workspace-runs logs` | `client.workspaceRuns.listEvents()`, `client.workspaceRuns.streamEvents()` | `client.workspace_runs.list_events()`, `client.workspace_runs.stream_events()` | | Workspace Run | Cancel | `cancel_workspace_run` | `crownest workspace-runs cancel` | `client.workspaceRuns.cancel()` | `client.workspace_runs.cancel()` | | Workspace Run | Evidence Bundle | `get_workspace_run_evidence` | `crownest workspace-runs evidence` | `client.workspaceRuns.evidence()` | `client.workspace_runs.evidence()` | Workspace Runs accept existing `.tar.gz`/`.tgz` archives, run a command in a curated CrowNest template, stream stdout/stderr events, and persist a durable Evidence Bundle. Use the CLI, SDK, API, or Crabbox to build the archive flow that fits your agent. MCP exposes primitive lifecycle steps, not the CLI-only `run-archive` convenience wrapper. ## Workspace Run Matrices [#workspace-run-matrices] | Operation | MCP tool | CLI command | TypeScript SDK | Python SDK | | --------------------- | ------------------------------------- | ------------------------------------------ | ------------------------------------------------------- | ------------------------------------------------------------ | | Create | `create_workspace_run_matrix` | `crownest workspace-run-matrices run` | `client.workspaceRunMatrices.create()` | `client.workspace_run_matrices.create()` | | Upload archive | `upload_workspace_run_matrix_archive` | `crownest workspace-run-matrices run` | `client.workspaceRunMatrices.uploadArchive()` | `client.workspace_run_matrices.upload_archive()` | | Create transfer | - | `crownest workspace-run-matrices run` | `client.workspaceRunMatrices.createArchiveTransfer()` | `client.workspace_run_matrices.create_archive_transfer()` | | Upload transfer bytes | - | `crownest workspace-run-matrices run` | `client.workspaceRunMatrices.uploadArchiveToTransfer()` | `client.workspace_run_matrices.upload_archive_to_transfer()` | | Finalize archive | - | `crownest workspace-run-matrices run` | `client.workspaceRunMatrices.finalizeArchive()` | `client.workspace_run_matrices.finalize_archive()` | | Run archive | MCP flow: create, upload, start | `crownest workspace-run-matrices run` | `client.workspaceRunMatrices.runArchive()` | `client.workspace_run_matrices.run_archive()` | | Start | `start_workspace_run_matrix` | `crownest workspace-run-matrices run` | `client.workspaceRunMatrices.start()` | `client.workspace_run_matrices.start()` | | Get status | `get_workspace_run_matrix` | `crownest workspace-run-matrices get` | `client.workspaceRunMatrices.get()` | `client.workspace_run_matrices.get()` | | List | `list_workspace_run_matrices` | `crownest workspace-run-matrices list` | `client.workspaceRunMatrices.list()` | `client.workspace_run_matrices.list()` | | Replay events | `replay_workspace_run_matrix_events` | `crownest workspace-run-matrices events` | `client.workspaceRunMatrices.listEvents()` | `client.workspace_run_matrices.list_events()` | | Cancel | `cancel_workspace_run_matrix` | `crownest workspace-run-matrices cancel` | `client.workspaceRunMatrices.cancel()` | `client.workspace_run_matrices.cancel()` | | Aggregate evidence | `get_workspace_run_matrix_evidence` | `crownest workspace-run-matrices evidence` | `client.workspaceRunMatrices.evidence()` | `client.workspace_run_matrices.evidence()` | The CLI `run` command is the one-shot flow for create, upload, finalize, and start. The SDKs also expose each primitive and event streaming. The REST endpoint inventory is in [Workspace Run Matrices](/docs/api/workspace-run-matrices). ## Code Contexts and Code Runs [#code-contexts-and-code-runs] | Resource | Operation | MCP tool | CLI command | TypeScript SDK | Python SDK | | ------------ | --------- | --------------------- | ------------------- | ------------------------------------------------------------- | --------------------------------------------------------------- | | Code Run | Run | `run_code` | `crownest code run` | `client.code.run()`, `sandbox.code.run()` | `client.code.run()`, `sandbox.code.run()` | | Code Run | Stream | - | `crownest code run` | `client.code.runStream()`, `sandbox.code.runStream()` | `client.code.run_stream()`, `sandbox.code.run_stream()` | | Code Context | Create | `create_code_context` | - | `client.code.createContext()`, `sandbox.code.createContext()` | `client.code.create_context()`, `sandbox.code.create_context()` | | Code Context | List | `list_code_contexts` | - | `client.code.listContexts()`, `sandbox.code.listContexts()` | `client.code.list_contexts()`, `sandbox.code.list_contexts()` | | Code Context | Get | `get_code_context` | - | `client.code.getContext()`, `sandbox.code.getContext()` | `client.code.get_context()`, `sandbox.code.get_context()` | | Code Context | Delete | `delete_code_context` | - | `client.code.deleteContext()`, `sandbox.code.deleteContext()` | `client.code.delete_context()`, `sandbox.code.delete_context()` | `run_code` uses artifact promotion by default. Inline display outputs stay inline when safe; rich outputs are promoted to Artifacts; oversized, unsafe, or unsupported outputs are reported as rejected outputs. ## Workspace files [#workspace-files] | Resource | Operation | MCP tool | CLI command | TypeScript SDK | Python SDK | | -------------- | ----------------- | ----------------------- | ----------------------- | ----------------------------------------------------------- | ------------------------------------------------------------- | | Workspace file | Read text | `read_file` | `crownest files read` | `client.files.read()`, `sandbox.files.read()` | `client.files.read()`, `sandbox.files.read()` | | Workspace file | Write text | `write_file` | `crownest files write` | `client.files.write()`, `sandbox.files.write()` | `client.files.write()`, `sandbox.files.write()` | | Workspace file | Upload local file | - | `crownest files upload` | `client.files.write()` | `client.files.write()` | | Workspace file | List directory | `list_files` | `crownest files list` | `client.files.list()`, `sandbox.files.list()` | `client.files.list()`, `sandbox.files.list()` | | Workspace file | Stat | `stat_file` | `crownest files stat` | `client.files.stat()`, `sandbox.files.stat()` | `client.files.stat()`, `sandbox.files.stat()` | | Workspace file | Make directory | `make_directory` | `crownest files mkdir` | `client.files.mkdir()`, `sandbox.files.mkdir()` | `client.files.mkdir()`, `sandbox.files.mkdir()` | | Workspace file | Move or rename | `move_file` | `crownest files move` | `client.files.move()`, `sandbox.files.move()` | `client.files.move()`, `sandbox.files.move()` | | Workspace file | Delete | `delete_file` | `crownest files delete` | `client.files.delete()`, `sandbox.files.delete()` | `client.files.delete()`, `sandbox.files.delete()` | | Workspace file | Download URL | `get_file_download_url` | - | `client.files.downloadUrl()`, `sandbox.files.downloadUrl()` | `client.files.download_url()`, `sandbox.files.download_url()` | | Workspace file | Read bytes | `read_file_bytes` | - | `client.files.readBytes()`, `sandbox.files.readBytes()` | `client.files.read_bytes()`, `sandbox.files.read_bytes()` | | Workspace file | Write bytes | `write_file_bytes` | - | `client.files.writeBytes()`, `sandbox.files.writeBytes()` | `client.files.write_bytes()`, `sandbox.files.write_bytes()` | Public file APIs operate inside the Sandbox Workspace. Use `/workspace` paths unless a lower-level runtime command intentionally reads elsewhere. ## Artifacts [#artifacts] | Resource | Operation | MCP tool | CLI command | TypeScript SDK | Python SDK | | -------- | -------------------------- | --------------------------- | ----------------------------- | --------------------------------------------------------- | --------------------------------------------------------- | | Artifact | Create from Workspace file | `create_artifact` | `crownest artifacts create` | `client.artifacts.create()`, `sandbox.artifacts.create()` | `client.artifacts.create()`, `sandbox.artifacts.create()` | | Artifact | List for Sandbox | `list_artifacts` | `crownest artifacts list` | `client.artifacts.list()`, `sandbox.artifacts.list()` | `client.artifacts.list()`, `sandbox.artifacts.list()` | | Artifact | Get metadata | `get_artifact` | - | `client.artifacts.get()` | `client.artifacts.get()` | | Artifact | Download bytes | `download_artifact` | `crownest artifacts download` | `client.artifacts.download()` | `client.artifacts.download()` | | Artifact | Download URL | `get_artifact_download_url` | - | `client.artifacts.downloadUrl()` | `client.artifacts.download_url()` | | Artifact | Delete | `delete_artifact` | `crownest artifacts delete` | `client.artifacts.delete()` | `client.artifacts.delete()` | Artifacts are durable outputs copied out of the Workspace and indexed by CrowNest. A file becomes an Artifact only when you explicitly create one or when Code Run output promotion succeeds. ## Previews [#previews] | Resource | Operation | MCP tool | CLI command | TypeScript SDK | Python SDK | | -------- | ---------------- | ---------------- | -------------------------- | ------------------------------------------------------- | ------------------------------------------------------- | | Preview | Create | `create_preview` | `crownest previews create` | `client.previews.create()`, `sandbox.previews.create()` | `client.previews.create()`, `sandbox.previews.create()` | | Preview | List for Sandbox | `list_previews` | `crownest previews list` | `client.previews.list()`, `sandbox.previews.list()` | `client.previews.list()`, `sandbox.previews.list()` | | Preview | Get metadata | `get_preview` | - | `client.previews.get()` | `client.previews.get()` | | Preview | Revoke | `revoke_preview` | `crownest previews revoke` | `client.previews.revoke()` | `client.previews.revoke()` | Preview URLs are authenticated or token-mode private browser links. Public unauthenticated Preview URLs are not part of v1. ## API Keys [#api-keys] | Resource | Operation | MCP tool | CLI command | TypeScript SDK | Python SDK | | -------- | ------------- | ---------------- | ---------------------- | ------------------------- | -------------------------- | | API Key | Create | - | `crownest keys create` | - | - | | API Key | List metadata | `list_api_keys` | `crownest keys list` | `client.apiKeys.list()` | `client.api_keys.list()` | | API Key | Get metadata | `get_api_key` | - | `client.apiKeys.get()` | `client.api_keys.get()` | | API Key | Revoke | `revoke_api_key` | - | `client.apiKeys.revoke()` | `client.api_keys.revoke()` | You create API keys from the dashboard or the CLI, not from the SDKs. Programmatic surfaces can inspect and revoke metadata, but secret key values are only shown once at creation. ## Vercel AI SDK tools [#vercel-ai-sdk-tools] `@crownest/ai-sdk` is a compact starter set for Vercel AI SDK loops: `runCode`, `runCommand`, `readFile`, and `writeFile`. MCP is the complete model-callable parity surface for the operations in this matrix. ## Beta scopes [#beta-scopes] Backup scopes are visible in API-key and auth.md metadata for beta accounts: `backup:create`, `backup:read`, `backup:restore`, and `backup:delete`. They are feature-gated and are not listed as generally available operations in this matrix until the backup API surface is public. ## Next steps [#next-steps] * [Agent patterns](/docs/guides/agent-patterns) has multi-step recipes that use the matrix above. * [MCP](/docs/integrations/mcp) documents the default Sandbox model for MCP hosts. * [Authentication](/docs/api/authentication) lists the scopes each operation requires.