# FAQ

## The model

**What is a Space?** An agent's persistent workspace: its files, plus its own Postgres or Redis when it needs them.
Nothing runs for it while it is idle. [concepts.md](concepts.md#space)

**Is a Space a VM that stays up?** No. Each command gets a fresh microVM that exists only while the command runs. The
files persist; process memory and shell state (`cd`, `export`) do not. If you need state across commands, write it to a
file, use a service, or use `shark connect` (coming), which carries `cd` and `export` for you.

**Why one VM per command instead of one long-lived VM?** Because agents spend most of their time thinking, not running
commands (82.7 % model time vs 10.2 % commands and services over 3,921 public sessions, P88). A VM per command means
nothing runs, and nothing bills compute, between commands. The cost is a VM start per command: measured at 44 ms on
the hosted hardware ([numbers.md](numbers.md)).

**Can I run a server that stays up?** Yes, as an exposed process (`shark expose`): it sleeps when idle and wakes on the
next request, and gets a preview URL (private by default). **Live on the hosted node** (P130 flow PASS, 2026-11-07),
through the CLI and the API; billed while awake, by size, and not while asleep. Background processes
started by a command can also be kept as jobs where the node enables it (hosted `shark code` does: `shark ps`,
`shark kill bg-N`).

**Can I run Postgres?** Yes, as a per-Space service: commit `.shark/services.toml` with `[postgres]` and
`version = "17"`; commands reach it at `127.0.0.1:5432`. It sleeps when unused and wakes on connect (37–40 ms measured).
Beta: declaring it in an already-running Space is not yet measured end to end. Redis 7 works the same way.

**How do I get my code into a Space?** `shark cp -r ./repo myspace:repo`, the files API (`PUT /v1/spaces/{id}/files`,
archive upload), or `git clone` inside a command (GitHub is in the default egress allowlist).

**What happens if two commands write the same file at the same time?** Both run; the first to finish lands, the second
gets `shark_status: conflict` and its changes are not published. Re-run it. Commands touching different paths merge.

**Does reading a file start a VM?** No. File reads, listings and downloads are served from the committed tree, and do
not wake a hibernated Space.

## Reliability

**What if my client crashes mid-command?** The command keeps running (it is a resource, not a connection). Re-attach with
`shark logs <space> <op-id>` or `GET /v1/spaces/{id}/ops/{op_id}/events`. Resending the same request with the same
`op_id` never runs it twice.

**What does `429 lease_cap_reached` mean?** Your account already runs the maximum number of commands at once. The
command did **not** start. Wait `Retry-After` seconds and resend with the same `op_id`; the CLI and SDKs do this for
you.

**How long can a command run?** Sync calls up to 900 s; streaming or async calls up to 2 h. Asking for more is a `400`
that tells you the maximum, never a silent cut. [limits.md](limits.md)

**Is my data durable?** The Space's commits replicate in the background to an object store; `checkpoint` returns once the
current state is stored. Until you checkpoint, the exposure is the replication lag, which the API reports.

## Agents

**Does it work with Claude Code / Codex / Cursor?** Yes: install `shark`, paste the [AGENTS.md snippet](agents-md.md),
and the agent runs its commands with `shark run`. Unmodified Claude Code running next to the Space (shell shim) is a
self-hosted option. [agents.md](agents.md)

**With LangChain, LangGraph, smolagents, Prefect?** The Python SDK has integrations for each. Beta.
[integrations.md](integrations.md)

**Is there an MCP server?** `sharkfn` serves Read/Write/Edit/Glob/Grep over MCP from a Space's tree (self-hosted, beta).
For command execution, the CLI or a one-tool SDK integration is simpler and adds no tokens per request.

**Can I use the E2B SDK unchanged?** Not yet; E2B compatibility is not served (`e2b_compat: false` in
`/v1/capabilities`). The vocabulary map is in [concepts.md](concepts.md#vocabulary-shark-vs-e2b-daytona-modal-and-boat).

## Security and keys

**Can my agent see my API tokens?** Not if you store them as Space secrets with `expose: inject` (the default): the
command sees a placeholder and the node adds the real value on the way out, only toward the hosts you allow.

**Can my agent reach the internet?** Within the Space's egress policy. The hosted default is an allowlist with package
registries and GitHub; add hosts with `PUT /v1/spaces/{id}/egress`. Private ranges are always blocked.

## Account and billing

**How do I get access?** Early access: request it at [sharkmagic.si](https://sharkmagic.si). Your invite has a key and
the node URL.

**How much does it cost?** Plans: Shark Pro $5/month includes $5 of usage; Shark Studio $25/month includes $25; Shark Scale $100/month
includes $100. One active plan: included usage is spent first, then prepaid credits. Commands run on the standard
8 vCPU / 4 GiB shape at $0.12 per compute-hour, billed only while a command runs. Services are $0.03/h for
2 vCPU / 2 GiB and $0.06/h for 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 is not billed. [billing.md](billing.md#plans)

**What happens when my credits run out?** New work answers `402 credits_exhausted` and your Spaces hibernate; files stay
readable. Top up to continue.

**Is there a free tier?** The Shark Pro plan includes $5 of usage each month, and storage and egress each have a free
monthly allowance per Space. There is no separate free plan; promotions, when offered, are shown at checkout.

**GPUs? Windows? Docker inside a Space?** No GPUs and no non-Linux guests. Docker inside a Space is not tested or
documented today: do not rely on it.

**Who do I contact?** Access: [sharkmagic.si](https://sharkmagic.si). Security reports: see [security.md](security.md).