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.

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.

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:

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 and must be enabled again.
• Containers set SWAMP_API_KEY and SWAMP_SIGNIN_TOKEN from a collective token.
• 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 refresh the proof, save 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.