# Shark Magic

> Serverless sandboxes for AI agents. Each agent gets a persistent **Space**: its files, plus its own persistent
> services when it needs them. Each command runs in a fresh microVM that exists only while the command runs, so the
> time the model spends thinking runs no VM at all.

Status: **early access** on the hosted node (`https://hel1.sharkmagic.si`). Request access at
[sharkmagic.si](https://sharkmagic.si). Every route, flag and verb in these docs exists in the code; every number
comes from a pre-registered proof and says which machine and date it is from. What is not ready is marked **beta** or
**coming** where it appears.

## The model in six lines

1. **Space**: an agent's persistent workspace, files on a content-addressed filesystem, with optional Postgres or Redis
   that belong to it alone.
2. **Lease**: every command gets a fresh Firecracker microVM with its own kernel and the Space mounted. When the command
   ends, its file changes are committed and the VM is gone (44 ms per lease on the hosted hardware).
3. **Op**: a command is a resource with an `op_id`. Retries never run it twice; output can be re-attached from anywhere.
4. **Fork**: O(1) copies of a Space at an exact commit, up to 50 per call, for parallel attempts, evals and shards.
5. **Sleep and wake**: idle Spaces hibernate into ~57 KB on disk and wake on the next request (58 ms measured);
   services sleep and wake on connect (37–40 ms measured).
6. **Billing per second of work**: commands, awake services and processes, storage and egress; idle is not billed.

## Use it when

- Your agents spend most of their time thinking: in 3,921 public autonomous sessions the model was 82.7 % of the time
  and commands 10.2 % (P88, [billing.md](billing.md)).
- You run many agents, users or customers, each with its own files and services, mostly idle.
- You need bursts of fresh environments that start fast and vanish (24 new Spaces with a first command each finished in
  342 ms on the hosted hardware).
- You want exactly-once command semantics and secrets that never enter the sandbox.

## Do not use it (today) when

- **You need process memory across commands** (a REPL kept in RAM, a debugger session). Files persist; memory does not,
  except in services and kept processes.
- **You need GPUs, non-Linux guests, an SLA or multi-region.** None exist yet.

## Start here

- [Quickstart](quickstart.md): CLI or SDK, `echo hello` and a fork in under 10 minutes.
- [Concepts](concepts.md): every term once, and a vocabulary map from E2B, Daytona, Modal and boat.
- [Agents](agents.md) and the [AGENTS.md snippet](agents-md.md): point Claude Code, Codex, Cursor or your own loop at
  Shark.
- Reference: [API](api.md), [CLI](cli.md), SDKs for [Python](sdk-python.md) and [TypeScript](sdk-typescript.md),
  [errors](errors.md), [limits](limits.md), [framework integrations](integrations.md).
- Trust: [security](security.md), [numbers](numbers.md), [billing](billing.md), [FAQ](faq.md).
- Not sure Shark fits? [Fit finder](fit-finder.md): a prompt for your coding agent that maps your stack.