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

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

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

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

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, 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

With LangChain, LangGraph, smolagents, Prefect? The Python SDK has integrations for each. Beta. 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.

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

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. Security reports: see security.md.