# Shark Magic

> Serverless sandboxes for AI agents: each agent has a persistent Space (its files, plus its own persistent services when it needs them); each command runs in a fresh Firecracker microVM that exists only while the command runs; idle time (the model thinking) runs no VM and bills no compute.

## Key facts

- What: a Space is a persistent workspace (content-addressed files, optional per-Space Postgres 16/17 or Redis 7 that sleep and wake on connect). Every command (`exec`) gets a fresh microVM with its own Linux kernel (8 vCPU / 4 GiB), the Space mounted; file changes are committed whatever the exit code; the VM is then destroyed. Process memory and shell state (`cd`, `export`) do not persist between commands.
- Status: early access. Request access: https://sharkmagic.si
- Endpoints: node API `https://hel1.sharkmagic.si/v1` (Spaces, commands, files, fork); account service `https://api.sharkmagic.si/v1` (sign-in, keys, node tokens, placement, workspace and teams, credits); previews `https://<space-id>-<port>.preview.sharkmagic.si` (exposed processes: private by default, one-time 60 s login link, sleep when idle, wake on request; billed while awake by size; CLI and API, no SDK method yet).
- Auth: an account key `shk_live_<id>_<secret>` goes only to the account service: `POST https://api.sharkmagic.si/v1/token` (key as Bearer) returns a 5-minute node token and the node URL; node calls carry `Authorization: Bearer <node token>`. The CLI and SDKs do this themselves: set only `SHARK_API_KEY` (or `shark login --api-key -`). Do not set `SHARK_API`: it means direct mode (a self-hosted node's own keys), where an account key answers 401. The account comes from the key; another account's Space answers 404. Every account starts with a personal workspace; teams are opt-in (`shark org`). Scopes: spaces:read, spaces:write, exec, files:read, files:write, usage:read (default key) plus secrets:write, network:write, admin on request; `shark keys create --space SP` limits a key to one Space. Never put keys in prompts, code or the Space.
- Exactly-once: send `op_id` with each command (use the tool-call id); a retry replays the stored result (`"replayed": true`), never runs twice; a different request with the same `op_id` is 409 idempotency_mismatch. `Idempotency-Key` header on create and fork.
- Exec modes: sync JSON (timeout_s default 120, max 900), SSE stream (`Accept: text/event-stream`, max 7200), async (`"wait": false`, 202). A non-zero exit is HTTP 200 with `exit`; `shark_status` = ok | conflict (re-run with new op_id) | timeout | infra_timeout | infra_error (retry same op_id) | signaled.
- Fork: `POST /v1/spaces/{id}/fork {"count": 1..50, "inherit_labels": true}`: O(1) on files, copies env and egress, not secrets, processes or service memory.
- Secrets: `PUT /v1/spaces/{id}/secrets`; default `expose: inject` (command sees placeholder `shk_ph_…`, the node adds the real value only toward `scope.hosts`; the value never enters the VM); `expose: exec` is an explicit opt-in. Account secrets (`PUT /v1/secrets`, `shark secrets set --account`) reach every Space (`apply: all`, forks included) or only those that reference them (`apply: ref`); a Space secret of the same name wins. `shark secrets status <space> --json` lists what is missing with the fixing command.
- Background processes: on the hosted node a process a command leaves running (`cmd &`, `nohup`) is kept as a job of the Space (stderr: `shark: … keep running as job bg-…`) and answers later commands at `127.0.0.1:<port>` (beta: 10–20 s to come up, not visible to later `ps`, cannot be stopped from inside the Space yet; start it with `timeout N`). Python: system pip is refused, use a venv (`python3 -m venv .venv && .venv/bin/pip install …`).
- Egress: per Space, `PUT /v1/spaces/{id}/egress {"mode": "allowlist"|"deny"|"open", "allow": [...], "base": "coding"|"none"}`; hosted default allowlist + package registries and GitHub; private ranges always denied.
- Errors: `{"error": {"code", "message", "retryable", "request_id", "details"}}`; retryable 429/503 carry Retry-After. 402 credits_exhausted (top up; files stay readable), 429 lease_cap_reached (command did not start; retry same op_id), 429 quota_exceeded, 503 out_of_capacity, 507 insufficient_storage, 422 unsupported (not served on this node yet).
- Limits (hosted defaults; live values: `GET /v1/quotas`, `GET /v1/capabilities`): per account, by class: 7 Spaces awake at once, 20/10/50 Spaces held and 4/2/6 commands at once (new / promo-only / standard; partner, for design partners and SDK platforms: 200 held, 100 awake, 12 at once; `429 quota_exceeded` with `details.quota` spaces|awake|label_spaces|label_awake and `details.raise`, `429 lease_cap_reached`); per-label limits cap each end user of a platform (`shark quotas labels set end_user --awake 3`), 50 GiB disk per account, sync output last 1 MiB per stream, op output kept 7 days (32 MiB per stream), file upload 512 MiB, archive 2 GiB, 100 requests/s per key.
- Measured on the hosted hardware (AX41, 2026-11-05): lease 44 ms; create → first command 65 ms; 24 new Spaces with a first command in 342 ms; sleeping Space wakes in 58 ms; sleeping Postgres answers in 37–40 ms; 91–96 % of a command's time is the user's command.
- Billing: plans Shark Pro $5/month (includes $5 usage), Shark Studio $25/month (includes $25) and Shark Scale $100/month (includes $100); one active plan, included usage spent before prepaid credit (no roll-over). Compute on the standard 8 vCPU / 4 GiB shape is $0.12 per compute-hour, billed per second only while a command runs; services are $0.03/h (2 vCPU / 2 GiB) and $0.06/h (4 vCPU / 4 GiB; standard service rate $0.06/h); storage is $0.08/GiB-month with the first 5 GiB free per Space per billing cycle; egress is $0.03/GB with the first 10 GiB free per Space per billing cycle. Overage only; idle and file reads are free. Prices are published here and in billing.md; live limits from `GET /v1/quotas`.
- Not supported today: GPUs; non-Linux guests; process memory across commands; services/snapshots/webhooks/events API routes (422); E2B SDK compatibility. Coming on the hosted node: `shark connect` (exposed processes and preview URLs are live).

## CLI cheat sheet

```sh
shark login --api-key -                                    # store an account key (prompted or stdin); a person: shark login
shark create --name demo                                   # prints the Space id
shark quotas --json                                        # your caps with current use (spaces, awake_spaces, …)
shark run demo -- 'npm ci && npm test'                     # stream output; exit = the command's exit code
shark run demo --detach -- 'make long'; shark logs demo <op-id>
shark fork demo -n 3                                       # O(1) copies
shark cp -r ./repo demo:repo ; shark cp demo:out.json .    # files in and out (reads start no VM)
shark ops demo ; shark files ls demo ; shark usage
shark hibernate demo ; shark wake demo ; shark rm demo
shark code --agent claude --remember account --repo owner/name demo ; shark code --continue demo   # a coding agent in the Space (beta; --agent list; no terminal: --agent or a remembered one, else harness_required); back to its last conversation
shark expose demo 3000 -- npm run dev ; shark open demo 3000 ; shark expose demo --rm 3000   # a preview (billed while awake)
shark connect demo                                    # coming on the hosted node
```

## Docs

- [Overview](index.md): what Shark is, when to use it and when not.
- [Quickstart](quickstart.md): CLI and SDK (Python, TypeScript) paths to `echo hello` and a fork, with expected output.
- [Concepts](concepts.md): Space, lease, op_id, services, exposed processes, fork, hibernation, durability, secrets, egress, keys, credits; vocabulary vs E2B, Daytona, Modal and boat.
- [What you can do](what-you-can-do.md): the jobs SharkBox does well (coding agent, tests, forks, UI evidence, previews, services, secrets), a recipe for each, and what it does not do yet.
- [Agents](agents.md): Claude Code, Codex and Cursor via `shark run`; your own loop via the SDK with op_id = tool-call id; unmodified Claude Code via the shell shim and `shark-rg`; `sharkfn` over MCP.
- [shark code](shark-code.md): Claude Code, Codex or OpenCode running inside your Space (beta): repository, terminal, conversation history, model credentials.
- [AGENTS.md snippet](agents-md.md): paste-ready instructions for AGENTS.md / CLAUDE.md, and the Claude Code skill (`shark skills install`).
- [HTTP API](api.md): every /v1 route with scope, status (GA-path, beta, coming), bodies and the route → CLI → SDK map.
- [CLI](cli.md): every `shark` verb, configuration and exit codes.
- [Python SDK](sdk-python.md): every class and method (signature, parameters, return type, errors, example): Spaces and their sdk defaults, commands, files, background jobs, secrets, egress, GitHub, usage, async client.
- [TypeScript SDK](sdk-typescript.md): the same for TypeScript, and what only the Python SDK has.
- [Errors](errors.md): every error code with retryable, Retry-After and what to do.
- [Limits](limits.md): timeouts, sizes, quotas and how to read your live values.
- [Framework integrations](integrations.md): LangChain, LangGraph, smolagents and Prefect with the Python SDK.

## Trust

- [Security](security.md): what we do (microVM per command, secrets outside the VM, egress policy) and how to report a vulnerability.
- [Numbers](numbers.md): measured numbers with machine, date and proof id; what is not ready.
- [Billing](billing.md): plans, usage rates, credits and what is metered.
- [FAQ](faq.md): short answers.

## Optional

- [Fit finder](fit-finder.md): a prompt to paste into your coding agent that maps your deployed agents and where Shark fits or does not.
- [CI and Playwright (design note)](use-cases/ci-playwright.md): planned, not measured.
- [All docs in one file](llms-full.txt)