Automating Swarmfile

Swarmfile is built to run without a person at a keyboard: a render-farm node, a CI job, a coding agent, or a seed box can mount, sync, and report on a project on its own. This page is the map - which credential to reach for, the surfaces that are meant to be scripted, and what is deliberately not a public API.

The credentials#

Project API keys are org-owned machine identities. A key is walled off to one project: it cannot read or write anything else in the org, and it is never treated as an owner or admin, no matter who minted it. Mint, list, revoke, and set a per-key request ceiling with swarmfile api-key (admin or owner), or from the dashboard's API keys page. The dashboard page also gives a key its own monthly spend budget - a dollar ceiling below the org's spend cap; enforcement uses the lower of the two, and a key over its budget has only its own writes paused. See CLI: api-key.

Personal access tokens are not a separate identity - a PAT resolves to you, and every access check runs against your own current role, so it can never do more than you can right now and it dies with your access, with nothing separate to clean up. Mint one under Settings → Access Tokens (self-serve for any member; up to 20 active per member, per org, optionally expiring). See Personal access tokens.

Both are shown in full exactly once at creation, both are revocable with immediate effect, and both are audited. Two more rules worth knowing:

• On a machine with both an API key and a leftover SWARMFILE_OIDC_REFRESH_TOKEN, the API key wins - and the engine logs the choice rather than picking quietly.
• If your org enforces an authentication policy, project API keys are exempt (they're org-provisioned machine identities), while a PAT snapshots the factors and email assertion of the session that minted it - a token minted before you enrolled stops satisfying the policy when enforcement begins.

Running an engine headlessly#

Mint a key for the project it serves, then hand it to the engine as SWARMFILE_API_KEY:

# On a machine where you're an org admin/owner:
swarmfile api-key create render-farm-04 --project proj_9f2a

# On the headless machine:
export SWARMFILE_API_KEY=sf_key_...
export SWARMFILE_ORG_ID=...
export SWARMFILE_PROJECT_ID=proj_9f2a
swarmfile-engine

Key minting is a hard plan allowance, not a soft one: Free 1, Starter 2 per seat (floor 5), Pro 5 per seat (floor 10), plus key packs. A mint past the cap is refused with keys_cap; revoking frees the slot immediately, and a downgrade blocks new mints without revoking keys you already have. See Billing & Plans.

Pin a key's own rate limit when a farm node should burst above the plan default:

swarmfile api-key rate-limit <key-id> 1000

For the full per-agent recipe - a labeled mount per agent and a shared dependency cache - see Coding Agents.

Scripting the CLI#

• --json (global) makes the CLI print the engine's raw response - the intended path for scripts - and a usage error comes back as {"code":"usage_error",…} instead of prose.
• Exit codes: 0 success, 1 error, 2 a refusal a script should act on (permission, quota, a conflict that needs a human), 3 a long operation detached. See the CLI reference.
• Long operations (merge, commit, checkout, materialize, project delete, and more) wait and print their result by default. --no-wait, or Ctrl-C, returns the operation id (exit 3) and the work carries on in the engine; collect the outcome later with swarmfile op - even after an engine restart.

CI#

There are two shapes, and they compose:

• Swarmfile's own runner - a headless engine that watches a branch and runs a job on every matching commit or tag, from an in-place checkout with no clone and no FUSE. See Runner (Headless CI).
• Your existing CI reporting a check - any system that can make two authenticated HTTP calls can gate a protected branch's require checks to pass rule through /runner-runs, using the same project API key a runner uses. The runner guide has the exact two-call contract: Reporting checks from your own CI system.

A headless engine authenticating with an API key also serves git clone and git push through the remote helper, once git access is enabled for the project - see Cloning a Project with Git.

Webhooks#

Webhooks deliver a signed HTTP POST to a URL you control when something happens in the org - no polling. An org-wide webhook is owner-managed, retried, logged, and auto-disabled after repeated failure; a personal webhook is a fire-and-forget notification channel for your own account. Deliveries are made on a periodic schedule, not in real time.

The full envelope, signature verification, event kinds, and limits live in Webhooks. The automation-relevant part: an API key cannot manage webhooks or any other org-wide admin surface - that's deliberate. Manage them from a script with a personal access token instead, which acts as you.

Rate limits#

Request budgets are per-user and per-org, counted in requests rather than bytes, and content streaming isn't counted. A PAT shares its owner's per-user window; an API key gets its own window at the plan's per-user default, adjustable per key. The engine batches and paces bursts against the budget the hub reports - burst behavior is covered in Coding Agents.

What isn't a public API#

There is no published REST API reference and no multi-language SDK. The supported programmatic surfaces are the ones on this page: the swarmfile CLI (with --json), headless engines authenticated by API keys, the /runner-runs check API, and webhooks. A personal access token can reach other routes your role can reach, but nothing beyond those four carries a stability contract - treat anything else as internal and subject to change.

Handling the credentials#

• Copy a secret once and store it in a secret manager or your CI's secret store - never in the repo, an image layer, or shared shell history.
• Prefer an API key over a personal refresh token on shared machines; revoke a key the moment a node is retired.
• Keys are org-owned: deleting a project revokes its keys with it, and every mint, revoke, and rate-limit change lands in the org's Activity feed.

Where to go next#

• CLI: api-key - mint, list, revoke, and cap keys.
• Personal access tokens - the script credential that acts as you.
• Runner (Headless CI) - the runner, external check reporting, and ref materialization.
• Coding Agents - one mount per agent and a shared cache.
• Webhooks - event kinds and signature verification.
• Billing & Plans - key allowances and packs.