# What you can do with SharkBox

> **SharkBox is the devbox side of Shark Magic**: `shark code` puts a coding agent (Claude Code, Codex, OpenCode) in a
> persistent Space and gives every command it runs its own fresh microVM. The agent keeps working while you are away;
> idle time runs no VM and bills no compute. The same primitives are in the HTTP API and the Python/TypeScript SDKs, so
> a platform can build the same flow without a human terminal.

Status legend: **GA** (on the hosted node today), **beta** (works, still changing), **planned** (design note, not
measured), **not available** (do not promise it).

## The model in four lines

1. **Space**: the agent's persistent workspace: files with history, optional Postgres or Redis that belong to it alone.
2. **Command = fresh microVM**: every command gets its own Linux VM with the Space mounted; the VM exists only while the
   command runs. File changes are committed whatever the exit code; process memory and shell state do not persist.
3. **The agent keeps working**: the harness lives in the Space's session VM. You attach from any terminal and detach
   without stopping it; it sleeps only when it is neither working nor waiting for you.
4. **Fork and sleep**: a Space forks in O(1) for parallel attempts, and a sleeping Space or service wakes on the next
   request. Thinking time costs no VM.

## Pick your job

| job | what SharkBox gives you | start with | status |
|---|---|---|---|
| A coding agent on a repository | the harness runs in the cloud; your laptop only shows the terminal | `shark code --repo acme/api --agent claude` | **beta** |
| Run one command in a clean VM | fresh 8 vCPU / 4 GiB VM, streamed output, exact exit code | `shark run demo -- 'npm ci && npm test'` | **GA** |
| Parallel attempts, evals, shards | O(1) copies of a Space at an exact commit (up to 50 per call) | `shark fork demo -n 8` | **GA** |
| UI evidence for a pull request | screenshots, Playwright flows, recordings and traces from inside the command | `shark screenshot`, a Playwright script | **beta** |
| A preview URL for a dev server | a sleeping exposed process with a private, one-time link | `shark expose demo 3000 -- npm run dev` | **beta** |
| A database per Space | Postgres 16/17 or Redis 7, initialized once, woken on connect | `.shark/services.toml` | **beta** |
| Secrets the agent cannot read | placeholders in the VM; the real value only toward the allowed hosts | `shark secrets set demo OPENAI_API_KEY --preset openai` | **GA** |
| Git and GitHub without per-Space setup | connect once per account; every devbox Space gets `git`/`gh` and a commit identity | `shark github connect` | **beta** |
| Move code between machines | copy files in and out with no clone and no running VM for reads | `shark cp -r ./repo demo:repo` | **GA** |
| Long jobs and background processes | `--detach` an op and re-attach its output; `&` leaves a kept job of the Space | `shark run demo --detach -- 'make long'` | **GA** / **beta** |
| CI shards and burst environments | one Space per pipeline, one fork per shard, one VM per shard command | see [the CI/Playwright note](use-cases/ci-playwright.md) | **planned** |
| Sensitive industries, on-prem | not offered today; the node is designed to be movable | — | **not available** |

## Recipes

### A coding agent that survives your laptop

```sh
shark login
shark code --repo acme/api --agent claude --auth subscription
```

`Ctrl-\` or `~.` detaches and leaves the agent running; close the terminal, lose the network, or get a new laptop. From
any machine: `shark attach acme-api` rejoins it (last output replayed), and `shark logs acme-api` shows what it printed
while you were away. `shark stop acme-api` ends it. `Ctrl-C` interrupts the agent; use `--on-ctrlc detach` if you want
`Ctrl-C` to detach too. See [shark code](shark-code.md).

### Tests, builds and a clean environment

```sh
shark run demo -- 'npm ci && npm test'
shark run demo --cwd web -- 'npm run build'
```

The command runs in a fresh VM; the files it changes stay in the Space. A dropped CLI connection resumes from the last
event; an `op_id` makes a retry exactly-once. See [CLI](cli.md).

### Parallel attempts without cloning N times

```sh
shark fork demo -n 8        # prints eight Space ids at the same commit
shark run <id> -- 'npx playwright test --shard=1/8'
```

Forks copy files in O(1), not histories of processes or service memory. Use one fork per attempt, per eval sample or
per test shard; delete them when done. See [API](api.md) and [concepts](concepts.md).

### UI evidence: screenshots, flows, recordings

```sh
# terminal 1 (bounded, as a kept job of the Space)
(timeout 1800 npm run dev -- --port 5173 > dev.log 2>&1 &)

# same or a later command
shark screenshot http://127.0.0.1:5173/ shots/home.png --size 1280x800
shark screenshot http://127.0.0.1:5173/login shots/login-mobile.png --size 390x844
```

`shark screenshot` waits for the URL, runs the image's headless Chromium once, validates the whole PNG and exits 0 only
when the file is on disk. For a flow, use a Playwright 1.56 script in one command; the image ships Chromium and ffmpeg,
so `playwright install` is not needed. A browser cannot stay open between commands; there is no desktop or computer
use. The screenshot is a capture of the web page, not the operating system. See the [CLI](cli.md) and
[shark code](shark-code.md).

### A dev server with a URL that sleeps

```sh
shark expose demo 3000 --cwd app -- npm run dev
shark open demo 3000          # one-time login link (private by default)
```

The process starts on the first connection and sleeps after 30 s idle; the next request wakes it. Your browser is the
only place the URL has to be reachable. See [concepts](concepts.md) and [CLI](cli.md).

### A database that belongs to the Space

```toml
# .shark/services.toml
[postgres]
version = "17"
```

The service is initialized once, restored from a snapshot, and sleeps when idle; connect from a command with the
`DATABASE_URL` the Space exposes. Redis 7 works the same way.

### Secrets the agent cannot read

```sh
shark secrets set demo OPENAI_API_KEY --preset openai
shark secrets status demo --json
```

The command sees a placeholder; the node swaps in the real value only toward the hosts the secret is scoped to, and
never writes it into the Space. Egress is a per-Space allowlist: a command cannot reach a host the Space does not
allow. See [security](security.md) and [concepts](concepts.md).

### Move a repository between machines

```sh
shark cp -r ./repo demo:repo
shark cp demo:dist ./dist
```

Reads start no VM. A fork gives you a second checkout of the same files without a clone; `checkpoint` gives you a
named commit to return to.

### Rejoin the agent from anywhere

```sh
shark attach demo            # the running agent, last output replayed
shark attach demo --view     # watch only
shark logs demo              # what it printed while you were away
shark ls                     # working | waiting-for-you | idle | asleep
```

This is the mobile/laptop story: the terminal is a viewer; the agent is on the node. Closing the viewer does not
stop the work.

## Cool combinations

- **Agent swarm.** One Space for the task, `shark fork -n K` for K attempts, then compare the diffs and keep the best;
  the copies share the bytes they did not change.
- **Proof attached to a pull request.** The agent starts the app, takes screenshots or a Playwright recording, and the
  files are in the Space for the PR. No browser install, no runner.
- **A workspace that moves.** Files live in the Space, not on a machine; the next command may run anywhere the node
  places the Space.
- **Burst data jobs.** A fresh VM per command for a one-off ETL or a scrape; the Space keeps the results and the
  scripts, the VM disappears.
- **A platform, not a terminal.** The same Space/command/fork primitives are in the API and SDKs: give each customer
  or end user a Space, run their agent's commands, fork for parallel work, and bill per second of work.
- **Secrets that stay out of the sandbox.** Give an agent a database or an API key without ever writing the value into
  the VM or the logs.

## What is beta, planned or not available

| thing | status | note |
|---|---|---|
| `shark code` (the agent in the Space) | **beta** | Claude Code, Codex, OpenCode; detach and rejoin; sleeps when idle |
| Browser screenshot | **beta** | one capture per command via `shark screenshot`; the image ships Chromium |
| Scripted Playwright, video and trace | **beta** | use the image's Chromium/ffmpeg; pin Playwright 1.56 |
| Desktop / computer use (OS GUI, native apps) | **not available** | no X server, no desktop; web-page automation only |
| WebKit, Firefox or a non-Linux guest | **not available** in the image | installing one needs egress and is not verified |
| Process memory across commands | **not available** | files persist; a RAM-resident REPL does not |
| On-prem / BYOC | **planned** | not offered today; say so rather than promise it |
| CI shards end to end | **planned** | the building blocks exist; the measured recipe does not |

## How an agent should choose

1. Need a shell command in a clean VM? `shark run`.
2. Need a coding agent that keeps working while the user is away? `shark code` (and `shark attach` to rejoin).
3. Need N independent tries? `shark fork`, then one `shark run` per copy.
4. Need a UI screenshot? `shark screenshot`; for a flow, a Playwright script in one command.
5. Need a URL? `shark expose` and `shark open`.
6. Need a database? add `.shark/services.toml` and connect with `DATABASE_URL`.
7. Need an API key? `shark secrets set`; never put the value in a prompt, a command or the Space.
8. Need files? `shark cp`.
9. Need GPUs, a desktop GUI, WebKit/Firefox, process memory across commands, or on-prem? Shark does not offer it
   today: say so plainly.

## Next

- [Quickstart](quickstart.md): `echo hello` and a fork in under 10 minutes.
- [Concepts](concepts.md): Space, lease, op, fork, services, secrets, egress.
- [shark code](shark-code.md): the agent in the Space, detach/rejoin, conversation history.
- [CLI](cli.md), [HTTP API](api.md), [Python SDK](sdk-python.md), [TypeScript SDK](sdk-typescript.md).
- [Limits](limits.md) and [security](security.md): what is capped and how to report a vulnerability.
- [CI and Playwright](use-cases/ci-playwright.md): the shard design note (planned).