# 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 | You need to | Use | Scope | |---|---|---| | Run an engine where nobody can complete a browser sign-in (render node, CI runner, agent fleet, seed box) | **Project API key** (`sf_key_…`) | Exactly one project | | Act as yourself from a script - provisioning, webhook management, anything your own role can reach | **Personal access token** (`sf_pat_…`) | Whatever your account can do, live | | Push and pull large objects with the stock `git-lfs` client | A **git-LFS credential** - a project API key minted from the project's git-LFS tab | That project's LFS traffic | | Work at a keyboard | Normal sign-in | - | **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](https://swarmfile.com/docs/admin/billing-and-plans#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](https://swarmfile.com/docs/cli/swarmfile#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](https://swarmfile.com/docs/admin/identity#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](https://swarmfile.com/docs/admin/identity#authentication-policy-require-mfa-andor-a-verified-email), 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`: ```bash # 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](https://swarmfile.com/docs/admin/billing-and-plans). Pin a key's own rate limit when a farm node should burst above the plan default: ```bash swarmfile api-key rate-limit 1000 ``` For the full per-agent recipe - a labeled mount per agent and a shared dependency cache - see [Coding Agents](https://swarmfile.com/docs/guides/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](https://swarmfile.com/docs/cli/swarmfile). - **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`](https://swarmfile.com/docs/cli/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)](https://swarmfile.com/docs/guides/runner-as-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](https://swarmfile.com/docs/guides/runner-as-ci#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](https://swarmfile.com/docs/guides/git-clone#turning-on-git-access). ## 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](https://swarmfile.com/docs/admin/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](https://swarmfile.com/docs/guides/coding-agents#how-fast-can-one-user-create-files). ## 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](https://swarmfile.com/docs/admin/operations#audit-log). ## Where to go next - [CLI: `api-key`](https://swarmfile.com/docs/cli/swarmfile#api-key) - mint, list, revoke, and cap keys. - [Personal access tokens](https://swarmfile.com/docs/admin/identity#personal-access-tokens) - the script credential that acts as you. - [Runner (Headless CI)](https://swarmfile.com/docs/guides/runner-as-ci) - the runner, external check reporting, and ref materialization. - [Coding Agents](https://swarmfile.com/docs/guides/coding-agents) - one mount per agent and a shared cache. - [Webhooks](https://swarmfile.com/docs/admin/webhooks) - event kinds and signature verification. - [Billing & Plans](https://swarmfile.com/docs/admin/billing-and-plans) - key allowances and packs.