Agent? Fetch sharkmagic.si/docs/llms.txt or this page as markdown

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#

Recipes#

A coding agent that survives your laptop#

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.

Tests, builds and a clean environment#

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.

Parallel attempts without cloning N times#

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 and concepts.

UI evidence: screenshots, flows, recordings#

# 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 and shark code.

A dev server with a URL that sleeps#

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 and CLI.

A database that belongs to the Space#

# .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#

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 and concepts.

Move a repository between machines#

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#

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#

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: echo hello and a fork in under 10 minutes.
• Concepts: Space, lease, op, fork, services, secrets, egress.
• shark code: the agent in the Space, detach/rejoin, conversation history.
• CLI, HTTP API, Python SDK, TypeScript SDK.
• Limits and security: what is capped and how to report a vulnerability.
• CI and Playwright: the shard design note (planned).