SWAMP ACCOUNT REQUIREMENT

Every Swamp command needs a swamp-club.com account, except the exempt commands listed below. Swamp checks for a credential, and that swamp-club.com has verified it, before a command does any work.

Credentials

Setting both SWAMP_API_KEY and SWAMP_API_KEY_FILE is an error. The requirement applies to every repository, including one using only a local filesystem datastore and a local_encryption vault. What a collective token may do once accepted depends on its scopes — see API Key Authentication.

Exempt commands

These run without a credential:

• bare swamp, and any line answered with --help, -h, --version or -V
• swamp help, swamp version, swamp completions and swamp update
• swamp auth, swamp auth login, swamp auth logout and swamp auth whoami

Every other command needs a credential, including swamp serve, swamp worker and swamp repo init. The one exception is swamp worker connect, which may pass through the serve that enrolls it instead — see Remote workers.

Verification

Each time swamp-club.com verifies a key, it returns a signed proof. The proof names the key it was issued for and its expiry, and is signed with swamp-club.com's Ed25519 key. Swamp stores it as auth_verified.json in its config directory.

While the proof is valid, Swamp runs with swamp-club.com unreachable.

A running swamp serve that passed on its own credential does not wait for exit to refresh. It writes the renewed proof to its config directory only when it owns that directory. A rejection during a refresh drops the serve's proof, and the serve stops vouching for remote workers.

Runs without a valid proof

With no valid proof, Swamp asks swamp-club.com before the command runs:

¹ The 24 hours are measured from a time Swamp records in its config directory. When the process cannot write that directory — it is read-only, or the process does not own it — the start is never recorded, and each run passes for as long as the server errors last. The warning then says the start cannot be recorded instead of naming a 24-hour limit. For a read-only container, set SWAMP_SIGNIN_TOKEN so runs pass on the token instead.

A key unknown to or revoked by swamp-club.com is blocked even when a valid proof is stored. With a valid proof, unreachable, refused and server-error answers run, with a warning.

Offline warnings

A run that passes without a live verification warns why:

<why> is either could not reach swamp-club.com or swamp-club.com is returning errors. In log mode the warning goes through the logger. In --json mode it is one JSON line on stderr, and stdout carries only the command's output:

{"warning":"Running offline (could not reach swamp-club.com); using your cached verification.","authMode":"offline"}

Exit codes

Blocked runs exit with code 75 when retrying can succeed (unreachable, refused, or over 24 hours of server errors) and 1 otherwise. The messages are listed in Account and sign-in errors.

Revocation

A revoked key is blocked at the next check with swamp-club.com:

Remote workers

swamp worker connect needs no credential of its own. Without one, it passes on a pass from the serve that enrolls it. Requires a serve at v20261008.183339.0-sha.231eda34 or later.

A worker with its own credential ignores the serve's pass and is checked as any other command. Only a missing credential waits for enrollment: a revoked key, or 24 hours of server errors, still blocks a worker before it connects.

A serve has no pass to give when it passed without a signed proof of its own — started offline on a signin token alone, or running unverified on server errors. A signin token never qualifies, because it has no expiry. Such a serve refuses a worker that needs a pass, and does so before it redeems the enrollment token. A serve older than v20261008.183339.0-sha.231eda34 sends no pass and redeems the token.

A worker the serve does not vouch for exits with code 1, auth_gate_blocked and reason no_credential. The message names one of four causes:

The fix for each is in Worker not vouched for by its orchestrator.

A worker without a credential has these limits:

• Commands that call swamp-club.com as an account fail inside its steps, among them swamp extension push, swamp issue and swamp auth whoami. The nested run has no API key to call with.
• Its step runners pass by checking that their parent is a live swamp at the same path. That check is unsupported on Windows and on musl-based Linux such as Alpine, so there every step is blocked. Run a keyless worker on glibc-based Linux or macOS, or give the worker a credential.

Signin tokens

A signin token is a proof issued when a collective token is created. It is read from SWAMP_SIGNIN_TOKEN, set beside SWAMP_API_KEY.

Store the signin token when it is shown. It cannot be retrieved later. With it, Swamp runs while swamp-club.com is unreachable. Without it, a run with no stored proof must reach swamp-club.com, so CI fails whenever swamp-club.com is unreachable or refuses the check. A lost signin token is replaced by creating a new collective token and revoking the old one. A signin token does not match any other key, so rotating the key needs a new signin token.

Personal API keys have no signin token. Run Swamp in CI shows where to find both values and how to set them.

CI

A run with no credential is blocked with:

swamp requires a swamp-club.com account to run.

  Run `swamp auth login` to create an account or sign in.

  In CI, set SWAMP_API_KEY and SWAMP_SIGNIN_TOKEN. For CI and daemons,
  see https://swamp-club.com/manual/reference/swamp-account-requirement

In CI, set SWAMP_API_KEY (or SWAMP_API_KEY_FILE) to a collective token and SWAMP_SIGNIN_TOKEN to the signin token issued with it. Create the collective token on the collective's Settings page on swamp-club.com, or with swamp auth token create --collective <slug>. Both values are shown once — see Signin tokens and Run Swamp in CI.

Daemons and containers

• swamp serve daemon enable and swamp worker daemon enable set SWAMP_CONFIG_DIR to the enabling user's config directory. Sign in as that user with swamp auth login, then run swamp serve daemon enable or swamp worker daemon enable again.
• A worker daemon enabled before the account requirement has no SWAMP_CONFIG_DIR. When it finds no credential at all, it passes through its serve as a remote worker; otherwise enable it again.
• Serve containers set SWAMP_API_KEY and SWAMP_SIGNIN_TOKEN from a collective token. Worker containers need neither when their serve vouches for them.
• swamp serve and swamp worker are checked when they start, not per request.

A process that does not own the config directory — a system daemon running as root against the enabling user's directory — reads it but never writes it. It does not save a refreshed proof (a running serve holds one in memory), the scope or identity cache, create identity.json, or update the autoupdate preferences. Because it caches no whoami answer, it calls swamp-club.com's whoami on every run. Writing would leave root-owned files that the user's own runs cannot read.