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

HTTP API v1#

Two hosts. The node serves Spaces, commands and files: https://hel1.sharkmagic.si/v1 (the hosted node). The account service, https://api.sharkmagic.si/v1, holds accounts, keys, balance and placement (below).

Auth. Every node request except healthz and capabilities needs Authorization: Bearer <node token>. With an account API key (shk_live_…), get the token from the account service: POST https://api.sharkmagic.si/v1/token (the key as Bearer; body {}, or {"space": "<id>"} for the node that holds that Space) → {"token", "expires_in": 300, "tenant", "scopes", "node": {"id", "url"}}. Send the call to node.url; mint a new token before it expires. The key itself never goes to a node. The CLI and the SDKs do this for you (quickstart.md). A self-hosted node in direct mode takes its own keys as the Bearer instead.

JSON in, JSON out, unless a route says otherwise. A machine-readable OpenAPI 3.1 contract is published alongside these docs at launch; where it and this page differ, this page follows the running server.

Status on every route: GA-path (served and tested), beta (served; local-only tests or a gap noted), coming (answers 422 unsupported today). Errors: errors.md. Limits: limits.md.

Conventions#

• Auth and tenancy. The account comes from the key; a body never chooses it. Another account's Space answers 404. Scopes per route are in brackets below.
• Ids or names. {id} accepts a Space id (tti-<32 hex>) or its name.
• Idempotency. Commands take an op_id (body, or header Shark-Op-Id for file writes); create and fork take an Idempotency-Key header. A retry with the same id replays the stored response ("replayed": true, header Shark-Replayed: true); the same id with a different request is 409 idempotency_mismatch.
• Headers on every response: Shark-Request-Id. Retryable 429/503 carry Retry-After.
• Pagination: ?limit= (default 50, max 1,000) and ?cursor=; responses are {"data": [...], "next_cursor": "…" | null}.
• Streams are Server-Sent Events: each event has an id: (a sequence number) and a JSON data:. Reconnect with Last-Event-ID to resume; nothing is lost or repeated. While a command is silent the server sends event: ping every 15 s.
• Additive versioning. Within v1 we only add endpoints, optional fields, response fields and enum values. Ignore fields you do not know.

System and identity#

Spaces#

A Space:

{"id": "tti-14bc859988847391c36a5d6bf889b300", "name": "curl-demo", "tenant": "<your-account>", "state": "ready",
 "labels": {}, "head": "d656da49…", "created_at": "2026-11-05T07:11:09.36Z", "last_activity_at": "2026-11-05T07:11:09.37Z",
 "durable": {"commit": "", "behind": false, "rpo_ms": 0, "fenced": false}, "session": false, "error": null}

state is ready or hibernated; fork_of appears on forks; profile is sdk or devbox; "keep_awake": true appears when the Space's jobs never sleep (billed awake).

settings (on GET /spaces/{id} and PATCH, not on the list):

The GitHub repository link of a Space lives in the account service: GET/DELETE /v1/spaces/{id}/github there (shark github link|unlink).

SDK Spaces and devbox Spaces (profile)#

Each Space has a profile, set when it is created and never inferred from the client. shark create and shark code make devbox Spaces (one developer: the account's secrets and GitHub in every Space). POST /spaces without a profile (the SDKs, a platform whose own users run in Spaces) makes sdk Spaces: nothing of the account reaches them unless the Space asks. Spaces made before profiles are devbox. Full table and tests: docs/sdk-vs-devbox-2026-11-07.md in the repository.

null in PATCH sets a field back to the profile's default. A fork takes its source's values unless the fork request sets them. Changing account_secrets or github needs secrets:write; keep_background, keep_awake and space_cli need exec. A refused value is 400 invalid_request with details.field. settings shows each value with its source (space, account, profile, default). GET /secrets of a Space lists the account secrets its selection keeps out with excluded: true (never a value).

GET /space-defaults [spaces:read] and PUT /space-defaults [spaces:write; account_secrets and github also secrets:write] {"account_secrets": "all"|"none"|null, "github": "account"|"off"|null, "harness": {"agent", "auth"}|null}: the account's defaults for every Space that does not set the field (then the profile's; harness reaches devbox Spaces only). The response's effective says what an sdk and a devbox Space get.

GET /agents [any key]: the coding agents (harnesses) this node's image runs, from its catalog (limited by the node's -agent-harnesses): {"data": [{"name", "title", "description", "auth": ["subscription", "api-key"], "keys": [{"env", "host", "preset"}], "resume"}], "source": "node"}. GET /capabilities lists their names in features.agents.

A bring-your-own GitHub token per Space needs nothing special: PUT /spaces/{id}/secrets with the github preset (GITHUB_TOKEN, hosts github.com, api.github.com); git and gh use it like the managed one.

Commands (ops)#

POST /spaces/{id}/exec [exec] — GA-path#

{"cmd": "npm ci && npm test", "op_id": "toolu_01AbC", "timeout_s": 900, "cwd": "web", "env": {"CI": "1"}}

Three modes, chosen by the request:

• sync (default): waits; 200 with the result below.
• stream: Accept: text/event-stream; events start, stdout, stderr ({"data", "encoding": "utf8"|"base64"}), detached, then exit (the result) or error.
• async: "wait": false; 202 with the op (state: running, events_url).

Result (sync, real response from a test server; timings there are not VM timings):

{"op_id": "qs-1", "exit": 0, "shark_status": "ok", "stdout": "hello\n", "stderr": "",
 "stdout_truncated": false, "stderr_truncated": false, "truncated": false, "replayed": false,
 "commit": null, "changed_paths": 0, "run_s": 0.0139, "timeout_s": 120,
 "lease": {"vcpu": 8, "mem_mib": 4096}, "wall_ms": 14.4, "queue_ms": 0.39, "shim_ms": 13.9, "wake_ms": null}

A non-zero exit is a normal 200. shark_status (ok, conflict, timeout, infra_timeout, infra_error, capacity_unavailable, signaled) says whether an unusual outcome came from Shark: concepts.md. commit is null when the command changed no file. wake_ms is set when the request woke the Space.

Ops#

Background processes#

The agent's Space credential under shark code (shk_agt_…) may call all four for its own Space (shark ps, shark logs bg-N, shark kill bg-N). Logs are the committed .shark/bg/<op>.log (header Shark-Granularity: commit).

On the hosted node a process a command leaves running (cmd &, nohup) is kept as one of these jobs; what that means inside a Space today: concepts.md.

Files#

Reads are served from the committed tree without starting a VM (and without waking a hibernated Space). Writes are ops: one commit each, stamped with Shark-Op-Id (header; generated if absent), merged like commands, so a write that races a command on the same path is 409 conflict with details.paths, never a lost update. Paths are relative to the Space root.

Secrets and egress#

PUT /v1/spaces/{id}/secrets
{"secrets": {
  "GH_TOKEN": {"value": "…", "scope": {"hosts": ["api.github.com"]}},
  "DB_URL":   {"value": "…", "expose": "exec"}
}}

• expose: "inject" (default) requires scope.hosts: the command sees a placeholder shk_ph_…; the node's egress proxy swaps in the value only toward those hosts (default location Authorization: Bearer). The value never enters the VM.
• expose: "exec" puts the value in the environment of commands that list it ("secrets": ["DB_URL"] in exec). The response carries warnings: [{"code": "secret_exposed_to_code", …}].
• A scope host the Space's egress does not allow is warned (scope_host_not_allowed).
• "keep_value": true instead of value changes a stored secret's expose, scope or apply and keeps its value (shark secrets edit); 400 invalid_request when nothing is stored under the name, or with a value too.

Account secrets (set once, used by every Space):

PUT /v1/secrets
{"secrets": {
  "OPENAI_API_KEY": {"value": "…", "scope": {"hosts": ["api.openai.com"]}},
  "GITHUB_TOKEN":   {"value": "…", "scope": {"hosts": ["github.com", "api.github.com"], "in": [{"kind": "basic"}, {"kind": "bearer"}]}, "apply": "ref"}
}}
PUT /v1/spaces/{id}/secrets
{"secrets": {"GITHUB_TOKEN": {"ref": "account"}}}

• Resolution, at each command: the Space's own secrets, then the account's apply: "all" secrets and the ones the Space references. A Space secret with the same name always wins. A fork gets the account's secrets (not the source Space's own secrets or references).
• They reach the command exactly as a Space's do (inject: a placeholder, the value only on the egress path to the scope; exec: only in commands that list the name). Sealed per account on the node, never returned.
• A reference to an account secret that does not exist is accepted with the warning account_secret_not_found and gives commands nothing until it is set.

PUT /v1/spaces/{id}/egress
{"profiles": ["essentials", "opencode"], "allow": ["api.example.com", "*.example.com", "db.example.com:5432", "203.0.113.0/24:5432"],
 "deny": ["*.githubusercontent.com"]}

profiles: names from GET /egress/profiles (aliases accepted; open = mode open, none = nothing). mode: allowlist (implied when profiles or deny is given), deny, or open (only accounts allowed it; else 403 plan_restriction). The old "base": "coding" | "none" still works when profiles is absent. Up to 256 allow and 256 deny entries; bare IPs, private and link-local ranges are refused with 400 invalid_request (details.field = allow[i], add[i], profiles[i], use[i], add_deny[i] or deny[i], details.host / details.profile, details.reason: ip_without_port, private_range, cidr_without_port, bad_cidr, bad_port, bad_name, invalid_host, too_many_entries, unknown_profile, included_by (removing a part of a harness profile: deny its hosts instead), deny_needs_allowlist). GET returns effective: hosts, entries (host, from: the profiles it comes from, "space" for yours), denied (host, from, by). An agent start adds its harness's profile (listed in auto). Details: concepts.md.

Exposed processes, previews and the terminal#

Exposed processes and previews: GA-path, live on the hosted node. Each exposed process runs in its own microVM; the whole flow (declare, private by default, one-time link, public toggle, logs, sleep after idle and wake on request, remove) passed end to end on the hosted node (P130 flow PASS, 2026-11-07). The terminal route (GET …/terminal, shark connect) is coming: tested locally only (P112), not yet verified on the hosted node. A node without the exposed-process runner answers 422 unsupported ("exposed ports and terminals are off on this node") on every route here; ports.available in GET /spaces/{id} says which. An exposed process is billed while awake, by size; asleep it is not (billing.md).

Preview URL: https://<space-id>-<port>.preview.sharkmagic.si.

GET /spaces/{id}/attach [exec] (beta) is the older terminal into a Space's session VM (Upgrade: shark-pty/1, used by shark attach); it answers 409 when the Space has no session VM ("session": false on the Space).

Account service: tokens, workspace, orgs, keys, logins#

At https://api.sharkmagic.si/v1 (the account service, not a node). Every account has a personal workspace from sign-up: keys, balance, plan and usage work without creating anything. Teams are opt-in. With your CLI login (shark login's access token) or an API key:

Errors: 403 user_credential_required (an API key on a route that needs a person), 403 personal_workspace (inviting or adding someone to a personal workspace, or deleting it: create a team instead).

From a browser (the dashboard)#

The dashboard calls the node directly. It asks the account service for a short-lived node token with the signed-in session: POST https://api.sharkmagic.si/v1/console/orgs/{org}/node-token (cookie session) → {"token", "expires_at", "expires_in" (≤ 600), "refresh_after_s", "scopes", "role", "node", "nodes": [{id, url}]}. The token carries the person's role in that org: owner, admin and member get every node scope (a member works on Spaces, secrets and egress included, exactly as with their CLI login; billing, keys and members stay owner/admin at the account service); at zero balance only read scopes ("billing": "credits_exhausted"). It is refused for another org (404) and without a session (401); it never outlives the session, and sign-out, an expired session, a role change or DELETE /v1/console/node-token make every node refuse it within ~2 s. The node answers CORS only for the dashboard origins it is configured with (sharkfs api -cors-origins, never *; the hosted node allows the console's origin, SHARK_CORS_ORIGINS in its config): the token goes in Authorization, never in a cookie, and no response carries Access-Control-Allow-Credentials. Scripts and agents use the same node routes with a node token from POST /v1/token (an account key) instead.

Usage#

Counts and durations only: usage never contains command text, paths or file contents. Balance and credits live in the account service (billing.md).

Coming (answer 422 unsupported today)#

/catalog/services, /spaces/{id}/services[/{name}[/checkpoint]] (declare services with .shark/services.toml instead: concepts.md); /spaces/{id}/snapshots, /snapshots/{snap_id}, /spaces/{id}/restore; /spaces/{id}/tokens (Space-scoped tokens); /spaces/{id}/connectors, /spaces/{id}/model-gateway; /events, /webhooks; /tenants (sub-accounts); /auth/device, /auth/token, /auth/revoke, /balance on the node (the account service at api.sharkmagic.si serves device login, tokens and balance). Each 422 names the phase in details.phase.

Route → CLI → SDK#

Every SDK method with its signature and errors: sdk-python.md, sdk-typescript.md.