Store headless/machine coding agent sessions

Agents that run in pipelines, sandboxes and scheduled jobs do work nobody watches. A machine credential lets that machine store its sessions like a person would, with nothing to sign in and nothing to refresh. The example below is a CI runner running Codex; a build box or a nightly job works the same way

Create the machine on your own computer, set the runner up, let Codex run headless, and the session arrives owned by ci-runner. Everything below stands on its own

1. Create the machine, on your own computer

Do this on a computer where you are signed in to kcap as yourself. The credential belongs to your account: it needs the owner or admin role, and the workspace has to sign in through single sign-on. Whoever runs this command is who the credential is tied to, so use the account that should own the runner’s sessions

Run it once; a second run with the same name is refused and prints no secret. It prints a client id, which is public, and a secret, which is shown once and never again. The secret goes to stdout alone, so it can go straight into a secret store without touching your screen or your shell history:

kcap machine create ci-runner | gh secret set KCAP_CLIENT_SECRET
gh secret set KCAP_CLIENT_ID --body client_01ABC...

That is everything the headless machine will need from you. Nothing else on your computer changes

2. Set up the headless machine

Everything in this section happens on the machine that will run unattended: the CI runner, the build box, the sandbox. In a pipeline it is the job’s steps; on a long-lived box it is a one-time setup

2a. Give it the two values

Put KCAP_CLIENT_ID and KCAP_CLIENT_SECRET in the environment of every process that will run kcap. In GitHub Actions that is the secrets you set above, exposed as env: on the job; on a box it is the service’s environment file. These two values are the machine’s identity: with them present, every kcap process on that machine exchanges them for a short-lived token at signin.kcap.ai, so the machine must be able to reach that host. There is no login step and no token to refresh

2b. Install the kcap CLI

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

The installer puts the kcap binary on the machine and then runs kcap setup with the flags after the second --:

--server-url is your workspace, the same address people use in the browser
--default-visibility chooses who can read what the machine stores, and it is a deliberate choice: a runner’s sessions carry prompts, tool output, source and deployment detail. org_public opens them to everyone in the organisation; project limits them to a project’s members. Set it here, on the machine, not on the credential. Do not leave it private: a private machine session would be readable by nobody, because the machine is not a person who can sign in and look
--skip-import stops setup looking for old transcripts on the machine, since there are none worth keeping

Because the two variables are already set, setup does not open a browser to sign in; it finds the machine identity and continues

2c. Install the coding agent and its hooks

Install whichever coding agent the machine will run, as you would on a laptop, then let kcap wire it up:

kcap setup

Setup finds the agents on the machine and installs their hooks, which is how a session gets stored. In a pipeline this runs on every job, after the agent is installed and before it runs

2d. Check the identity

kcap status

It should say the machine is authenticating as ci-runner. If it shows a person’s name instead, the two variables are not reaching the process

3. Run the agent

Run your coding agent on the machine exactly as before, interactive or headless (codex exec, claude -p, and the like). The session appears in Sessions owned by ci-runner, visible to the whole organisation

Rotation and revocation

Run these on your own computer, signed in as yourself, the same place you created the machine:

kcap machine list
kcap machine revoke service:9e96...

Secrets are never shown again, so rotating means creating a new machine, moving its two values into the secret store, and revoking the old one. Admins can also revoke from Administration → Integrations → Machines in the web UI

Keep the variables off your laptop

If either variable is set in an interactive shell, kcap stops using your own login and stores your sessions as the machine. kcap status warns when it sees them