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

CLI: shark#

One static binary for you and your agents (Linux, macOS; amd64, arm64). Install:

curl -fsSL https://dl.sharkmagic.si/install.sh | sh

It verifies the binary's sha256 against the release's SHA256SUMS before installing (details and the manual path: quickstart.md). shark version [--json] prints the build (version, commit, os, arch); shark update [--json] says whether a newer release exists (update_available, latest) and changes nothing; shark update --install downloads it, checks the same checksum and replaces the binary in place (error codes checksum_mismatch, update_check_failed, update_not_writable). SHARK_RELEASES_URL points both at a mirror with the same layout.

Cheat sheet#

shark login                                                # browser login with a one-time code
shark login --api-key -                                    # an account API key (stdin or a hidden prompt; CI: < keyfile)
shark whoami                                               # tenant (your account), credential, scopes
shark keys create --name ci > ci.key                       # an API key for CI (secret shown once)
shark org ls ; shark org use acme                          # personal workspace + teams; switch this login
shark org invite acme --email ana@example.com              # invite someone into a team (owner/admin)
shark code --repo acme/api                                 # a coding agent in the cloud on that repo (shark-code.md)
shark secrets set demo ANTHROPIC_API_KEY --preset anthropic --allow-egress   # value from a hidden prompt
shark egress add demo api.stripe.com                       # let the Space's commands reach one more host
shark quotas                                               # your limits, current use, limits class, node admission
shark quotas labels set end_user --awake 3                 # per end user: 3 Spaces awake (platforms)
shark create --name demo                                   # prints the Space id
shark run demo -- 'npm ci && npm test'                     # stream output, exit with the command's code
shark run demo --cwd web -- 'npm run build'                # run in a subdirectory
shark run demo --detach -- 'make long-job'                 # start it, print the op id, return
shark logs demo <op-id>                                    # re-attach to an op's output from anywhere
shark ops demo                                             # recent commands: op id, state, exit, shark_status
shark ps demo                                              # background jobs (bg-N); shark kill bg-1 demo stops one
shark fork demo -n 3                                       # three O(1) copies at the same commit
shark cp -r ./repo demo:repo                               # upload a directory (one commit)
shark cp demo:out/report.json .                            # download a file (no VM starts)
shark files ls demo [path]                                 # list files
shark hibernate demo ; shark wake demo                     # sleep now / wake now
shark usage --by space                                     # metered usage
shark ls ; shark rm demo                                   # list, delete

<space> is always a Space id or its name. Every verb has --help with examples (shark secrets --help), and shark --help lists them all.

Output, errors and exit codes#

Made to be driven by people and by agents alike:

• --json on every verb that prints a result (ls, whoami, create, rm, fork, ops, hibernate, wake, quotas, usage, balance, topup, secrets, egress, github, stop, logs <space>, run --detach, login, keys, org, logins): stdout is then exactly one JSON document, the result or {"error": {"code", "message", "hint", "status"}}. Progress lines ([shark: …]) always go to stderr.
• Errors in text mode: shark: <message> and, when there is a next step, next: <exact command> on stderr. The code is stable (not_logged_in, usage, not_found, missing_key, credits_exhausted, insufficient_scope, quota_exceeded, out_of_capacity, github_not_connected, clone_failed, not_a_terminal, confirmation_required, harness_required, cancelled, …; API codes as in errors.md). Never a stack trace.
• Exit codes: 0 done; 1 the API refused or failed (the code says why); 2 usage error, or not configured / not logged in; 125 Shark could not report a result (run, logs), or the agent's session VM, its terminal channel or the agent's start failed (code, attach: the [shark: … (code 125) …] line says which); otherwise the command's own exit code (run, logs <space> <op>, run-agent).
• No prompts you cannot avoid: a secret value comes from stdin when it is piped (a hidden prompt only on a terminal); --no-browser / --print where a browser would open; every confirmation has --yes. When stdin is not a terminal nothing asks: the command fails with the flag form in next: (not_a_terminal, confirmation_required). A question cancelled with q / Ctrl-C exits 130 (cancelled), nothing changed.
• Colors only when stderr is a terminal; NO_COLOR=1 (or TERM=dumb) turns them off. Tables have a header only on a terminal, so scripts can split lines on tabs.

Configuration#

The environment wins over the files. URLs must be https:// (plain http:// only to a loopback address, so a key never travels in clear).

Two modes. With an account key or a shark login (the hosted service), the CLI talks to the account service: it exchanges the key there for 5-minute node tokens and sends each call to the node that holds the Space. The key never reaches a node. Direct mode (SHARK_API set, or shark login --api-key - --api URL) sends the key to that one node as is: it is for a self-hosted node and that node's own keys. An account key in direct mode answers 401 unauthenticated, and the account verbs (balance, keys, org, …) answer needs_control_plane. To leave direct mode: unset SHARK_API and shark login --api-key - again (the login rewrites ~/.shark/credentials).

Account#

Spaces#

Commands#

shark run joins its arguments with spaces into one bash command line: quote the whole thing, shark run demo -- 'cd web && npm test'. Exit codes: the command's own code when it ran; 1 when the API refused it and nothing ran (for example the Space does not exist; the next: line says what to do); 125 when Shark could not report a result (the op goes on: shark logs <space> <op-id>); 2 for usage or configuration errors. When shark_status is not ok (conflict, timeout, infra error) it is printed on stderr.

Files#

Reads never start a VM and never wake a hibernated Space.

Live: exposed processes, previews, terminal#

expose and open are live on the hosted node (P130 flow PASS on metal, 2026-11-07): each exposed process runs in its own microVM, private by default, sleeps after its idle time and wakes on the next request. It is billed while awake, by size; asleep it is not (billing.md): remove the ones you no longer need with --rm. shark connect is coming: it passed its local gates (P112) but is not yet verified on the hosted node. On a node without exposed processes every verb here prints the node's 422 unsupported.

Expected (the output shape; the Space id is an example):

$ shark expose demo 3000 --cwd app -- node server.js
exposed node server.js on port 3000 (declared); it starts on the first connection and sleeps after 30s idle
preview: https://tti-ec8e46415dcc2dc3182daae2bc8a8aa2-3000.preview.sharkmagic.si/
private: open it with `shark open demo 3000`

Agent instructions: shark skills#

Local files only (no key, no network). The text ships inside the CLI; its source is skills/shark/ in the Shark repository (agents-md.md).

Secrets#

The value is read from stdin (pipe it), a hidden prompt or --from-file, never from argv (shell history and ps would keep it). Inject secrets (the default) never enter the VM: commands see a placeholder shk_ph_… and the node's egress proxy puts the real value only into requests to the scope's hosts (concepts.md).

Guided setup (a person at a terminal)#

shark secrets (or shark secrets setup [--account | <space>] [NAME] [--preset P …]) asks, one step at a time: where (the account, or one of your Spaces), the kind (a preset, custom, or the account's secret for a Space), the name, for custom the exposure (inject / exec, exec confirmed twice), hosts and where in the request, for the account which Spaces get it, for a Space whether to add the hosts to its egress, then the value (hidden, paste-friendly: a pasted newline does not submit; it says how long it is and whether it starts as the provider's keys do, e.g. sk-ant-, never what it is), and a review with the equivalent flag line. Nothing is sent before Save.

Keys: Enter = the default (forward), b or ← = back (the answers are kept; going forward again walks through them), q, Ctrl-C or Ctrl-D = cancel (nothing saved, exit 130), menus: ↑/↓ or a number. From the review you can jump to any step and come straight back. Flags given on the command line fill their steps. After saving it says what happens now ($NAME=shk_ph_…, the egress) and the next commands (shark secrets status, shark code). shark secrets set with a missing name or hosts on a terminal opens the same setup with what you gave; off a terminal it fails with the flag form.

Commands#

A Space secret with the same name as an account secret always wins in that Space (ls and status show the account one as shadowed).

shark secrets                                                                  # guided setup (a terminal)
shark secrets set demo ANTHROPIC_API_KEY --preset anthropic --allow-egress    # prompts, input hidden
gh auth token | shark secrets set demo GITHUB_TOKEN --preset github
shark secrets set demo STRIPE_KEY --host api.stripe.com < stripe-key.txt
shark secrets status demo --agent claude                                      # what is missing, and the fix
shark secrets edit demo STRIPE_KEY --add-host files.stripe.com                 # no value needed
pbpaste | shark secrets rotate demo STRIPE_KEY
shark secrets rm demo STRIPE_KEY --yes
pbpaste | shark secrets set --account OPENAI_API_KEY --preset openai   # every Space, forks included
shark secrets usage --account OPENAI_API_KEY --json

Every setup step has a flag#

The review prints the flag line of what you chose (never the value); shark secrets set with those flags and the value on stdin stores exactly the same thing (tested: cmd/shark/secrets_wizard_test.go, TestSetFlagParity).

status --json#

{"scope": "space", "space": "demo", "agents": ["claude"], "presets": [], "egress": {"mode": "allowlist", "source": "space"},
 "secrets": [{"name": "STRIPE_KEY", "scope": "space", "expose": "inject", "hosts": ["api.stripe.com"], "in": [{"kind": "bearer"}],
              "preset": "", "active": true, "shadowed": false, "missing": false, "egress_blocked": ["api.stripe.com"],
              "usage": {"available": true, "count": 7, "blocked": 0, "last_used": "2026-11-06T10:00:00Z"}}],
 "gaps": [{"code": "missing_secret", "severity": "error", "secret": "ANTHROPIC_API_KEY", "agent": "claude", "message": "…",
           "fix": "shark secrets set demo ANTHROPIC_API_KEY --preset anthropic --allow-egress < value.txt"},
          {"code": "egress_not_allowed", "severity": "error", "secret": "STRIPE_KEY", "hosts": ["api.stripe.com"], "message": "…",
           "fix": "shark egress add demo api.stripe.com"}],
 "ok": false}

ok is false while any gap has severity: "error"; the exit code is 0 either way (1 only when the API fails). Gap codes: missing_secret (a harness or --preset expects it; the fix is --from-account when the account has it as apply: ref), egress_not_allowed, account_secret_unset (a reference to no account secret), and the info ones shadowed, placeholder_blocked (requests carried the placeholder to a host outside the scope: usage shows where), egress_unknown (an older node does not say which hosts its egress allows). fix is a command to run as printed (a < value.txt means the value on stdin; HOST is yours to fill in).

Errors (stable codes, --json as everywhere): not_a_terminal (2: the guided setup without a terminal; the hint is the flag form), confirmation_required (2: rm without --yes off a terminal), cancelled (130: q, Ctrl-C or Ctrl-D in a question; nothing saved), no_value / bad_value (2: empty, under 8 or over 16 KiB, a control character, or a shk_ph_ placeholder pasted back), unknown_preset, unknown_agent (2), secret_is_account (2: rotate/edit of an account secret through a Space: the hint is the --account form), not_found (1), unsupported (1: a node too old for edit's keep_value; set it again with the value), usage (2).

A host the Space's egress does not allow is warned, with the command that fixes it. The old argv form NAME=VALUE still works (stored as --exec) but prints a deprecation warning; NAME=- and NAME=@file too.

Egress#

Changes apply from the next command (the agent's session VM: from its next start); forks inherit them. shark code --agent X adds X's profile by itself (and with an API key the key's provider); shark secrets set … --preset P --allow-egress adds P's profile. A refused entry is 400 invalid_request with details.field (add[i]/allow[i]/use[i]/add_deny[i]), details.host or details.profile and 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, deny_needs_allowlist); --json prints them.

shark egress profiles                               # the catalog
shark egress use demo +opencode +openrouter -docker-hub
shark egress show demo --effective                  # every host and the profile it comes from
shark egress denials demo --since 1h --json         # what was refused, and which profile has it

GitHub#

Connect GitHub once; every Space of your account can then use git and gh on the repositories you chose (new Spaces, existing ones and forks, with no per-Space step). The node keeps a managed GITHUB_TOKEN account secret (inject, apply all) fresh: short-lived App installation tokens, minted before a command when the current one is missing or expires within 15 min. Your commands see a placeholder; git clone/fetch/push over https and gh work as usual (git@github.com: URLs are rewritten to https), and commits default to your GitHub noreply address unless the Space sets its own user.name/user.email.

With several installations (your account and organizations), requests that name a repository (github.com/<owner>/…, api.github.com/repos/<owner>/…) get that owner's token; others (GraphQL, /user) get the default one (your own account's). shark code --repo needs no token step when the account is connected. Without the App (503 github_not_configured), gh auth token | shark secrets set --account GITHUB_TOKEN --preset github works.

The account's connection reaches devbox Spaces. An sdk Space (made by the API/SDK) gets it only with github: true (shark space set <space> --github on); its commit identity is --git-name/--git-email (git: {name, email}). A platform whose users install its own GitHub App registers it once and links each Space to one installation:

SDK: shark.github_app.register(app_id, pem), .link(space, installation_id, repos=[…]), .status(), .remove() (TS: shark.githubApp.*). Or, with a token you mint yourself, per Space: shark secrets set <space> GITHUB_TOKEN --preset github < token.txt (SDK: space.secrets.set("GITHUB_TOKEN", tok, preset="github")).

Coding agent and terminals in a session VM#

Details: shark-code.md.

Usage#

Other binaries (self-hosted and harness integration)#

shark service catalog (works anywhere):

postgres@16  port 5432  2 vCPU 1024 MiB  env DATABASE_URL PGDATABASE PGHOST PGPASSWORD PGPORT PGUSER POSTGRES_URL
postgres@17  port 5432  2 vCPU 1024 MiB  env DATABASE_URL PGDATABASE PGHOST PGPASSWORD PGPORT PGUSER POSTGRES_URL
redis@7      port 6379  1 vCPU  512 MiB  env REDIS_HOST REDIS_PORT REDIS_URL

Without SHARK_API and a key, shark create <dir>, shark fork, shark log, shark head and shark checkout work on a local Space store (SHARK_HOME): the early prototype of the content-addressed Space, no server and no VM.