Store sessions where nobody can sign in

A machine is an identity for places where nobody can sign in: CI runners, ephemeral agent sandboxes. It stores sessions like a user, is never an administrator or a project member, and authenticates with two environment variables that kcap exchanges for a short-lived token by itself. Store headless/machine coding agent sessions is the walkthrough; this page is the reference

Machine credentials are available on workspaces that sign in through single sign-on, and are switched on per workspace by Kurrent

Create

Signed in, with the organisation’s owner or admin role and kcap administrator rights:

kcap machine create ci-runner [--visibility org_public] [--role member]

The secret is printed once, to stdout alone; the client id and instructions go to stderr. Pipe stdout straight into a secret store. kcap machine list shows client ids any time; the secret is never shown again

Configure the runner

Variable	Value
KCAP_CLIENT_ID	The client id. Public
KCAP_CLIENT_SECRET	The secret. From the CI secret store
KCAP_URL	The workspace URL, when the image carries no profile

Install kcap and the agent’s hooks on the runner with the script installer and --no-prompt:

curl -fsSL https://www.kurrent.io/install | bash -s -- -- --server-url https://acme.kcap.ai --default-visibility org_public --skip-import

On Windows runners, put the setup options in KCAP_SETUP_ARGS before irm https://www.kurrent.io/install.ps1 | iex. A pre-baked image with hooks already installed needs only the variables. The token exchange calls signin.kcap.ai, which the runner’s egress must allow

Visibility

A machine’s sessions use the default_visibility of the profile it runs under, or org_public with no profile. project is not available, because a machine is never a project member. Unlike a person’s, a machine’s org_public sessions never fall back to private in personal repositories. Avoid private: nobody could read those sessions, because the machine cannot sign in to look

Verify

kcap status

The auth line names the machine credential. Run the agent as usual; its sessions appear owned by the machine

Rotate and revoke

kcap machine list
kcap machine revoke service:<id>

Revocation is immediate for new requests and cannot be undone; a token already held expires within the hour. Rotate by creating a replacement and revoking the old one. Admins can review and revoke under Administration → Integrations → Machines; creation stays in the CLI so the secret never passes through the server

Keep the variables off your laptop

With either variable set, every kcap process uses the machine, not you, including the sessions your own agents store. kcap status warns when it sees them in an interactive shell

Help me get unstuck

Message	Cause
You need the owner or admin role in this organization	Your organisation role is member
You need to be a kcap administrator to register a machine	The credential was issued but registration needs admin rights on the workspace
Machine credentials aren’t enabled	Not switched on for this workspace. Contact Kurrent
KCAP_CLIENT_ID is set but KCAP_CLIENT_SECRET is not	Half-configured runner
The machine credential was rejected	Wrong or revoked values. Revoke and create a fresh one
Sessions store but nobody can see them	The runner’s default visibility is private