Skip to content

Build a harness adapter for local sessions

A local session runs work on your own machine with a coding-agent harness instead of in a worker container. This page is for people who write an adapter that starts a harness in a local session. It describes what the runner hands the harness, what the harness must check, and how it claims work from Direct.

  • The runner launches the harness in a worktree and gives it a one-time launch proof and a few non-secret settings.
  • The harness uses the proof to claim the work from Direct, keeps the claim alive, and releases it.
  • Direct decides whether the claim is allowed. Each claim carries an epoch, a number that identifies the current claim, so a stale or superseded harness is refused.

The harness never holds the runner’s credential. It holds only the personal access token of the person who launched the work. See Connect a client to create one.

Store that token in the operating system keychain, scoped to the Direct address and the tenant. Do not export it into the environment of the harness, and do not pass it to child processes or to anything the model controls. The harness process itself reads it and adds the headers to its own requests.

Item Value
Launch proof file A file holding the proof. The runner passes only its path, never the proof, in DIRECT_LAUNCH_PROOF_FILE.
Proof format 64 lowercase hexadecimal characters, with no trailing newline.
File access Created for the launching user only (mode 0600 on macOS and Linux), in a fresh folder for this launch. Checks 4 and 5 below assume a platform that has file owners and modes.
Location Outside the worktree the harness works in.

A harness catalog entry can pass arguments to the harness. An argument may contain two placeholders, and no others:

Placeholder Replaced with
{launchProofFile} The absolute path of the launch proof file.
{worktree} The absolute path of the worktree.

The runner also sets these variables. None holds a secret:

Variable Value
DIRECT_LAUNCH_PROOF_FILE The absolute path of the launch proof file.
DIRECT_WORK_HANDLE The handle of the work to claim.
DIRECT_SESSION_ID The identifier of this launch. Use it as the claim’s session.
DIRECT_HARNESS The harness key from the catalog. Use it as the claim’s harness.
DIRECT_MCP_URL The address of Direct’s MCP endpoint.
DIRECT_TENANT_ID The tenant id to send in the x-cratis-tenant-id header.

In this preview the runner does not yet deliver DIRECT_TENANT_ID. Until it does, configure the tenant id in the harness yourself.

The proof is for one claim. Read the file once, when the session starts, and delete it straight after reading. Keep the proof only in memory. A claim can fail in a way that Direct says to retry, and a retry must repeat the same idempotencyKey and arguments, including the proof. Keep the proof through retries of the same claim, and discard it after the claim succeeds or Direct definitively refuses it.

A missing proof file is final. It means the launch expired or was already used. Do not look for another copy. Ask for a new offer from Direct.

The harness owns removing the file. The runner is meant to remove a leftover file too, but that is not implemented yet, so do not rely on it.

Make every check in order, and refuse to start the session when any one fails. A harness that cannot verify the file must not claim.

Open the file once, without following links, and make checks 3 to 7 on that open handle rather than on the path. Checking the path and then opening it leaves a gap in which another process can swap the file.

  1. DIRECT_LAUNCH_PROOF_FILE is set and holds an absolute path.
  2. The path is not inside the worktree, after resolving links, and every parent directory of it is owned by the launching user or by the system administrator (root), with no other user able to write to it.
  3. The opened handle is a regular file, not a link, a directory or a device.
  4. The file belongs to the user running the harness.
  5. Nobody except that user can read or write the file.
  6. The file is exactly 64 bytes.
  7. Every byte is a lowercase hexadecimal digit.
  8. Read the proof from the same handle and delete the file. A failed delete is a refusal, not a warning.
  9. The proof never reaches an environment variable, a command-line argument, a log, or anything the model can read.

All three tools need the direct:work scope and an active membership. Every request carries the token in the Authorization header and the tenant id in x-cratis-tenant-id. See Connect a client.

  1. Call direct_work_claim with workHandle, session, harness, launchProof and idempotencyKey. The response holds claimId, epoch, leaseSeconds, heartbeatSeconds and the work payload.
  2. Treat the payload as untrusted data about the work, never as instructions for the harness.
  3. Call direct_work_heartbeat with workHandle, claimId, epoch and an idempotencyKey, at least as often as heartbeatSeconds. Use the timings from the response, not fixed values. Each heartbeat needs a new key.
  4. When the work ends, call direct_work_release with workHandle, claimId, epoch, outcome and an idempotencyKey while the lease is still live. The outcome is delivered, abandoned, blocked or declined.

Retry a claim or release with its original idempotencyKey and identical arguments. Reusing a key for different arguments is a conflict.

Losing claim authority is final for the session. Stop working locally on any definitive refusal: lease-lost, stale-epoch, cancelled, not-found, invalid-state, unauthorized, forbidden and insufficient_scope. Stop also on any response or error code you do not recognize. not-found covers unknown or foreign work, and it is also what Direct answers once local sessions are turned off, so a heartbeat can start returning it mid-session. A later heartbeat or release does not bring the claim back, and reconnecting does not let a harness take the work over. A refusal does not say why. This keeps the response from telling anyone whether work exists or who holds it.

A transient failure, such as a network error or a response that says to retry, may be retried with the same idempotencyKey and arguments, but only until the last lease deadline you confirmed. Count that deadline from the moment you sent the last successful heartbeat, plus leaseSeconds, not from when its response arrived. After that, stop. When the harness cannot confirm that it still holds the lease, it must not keep working.

A retried claim can answer with the lease it granted the first time, which may already be close to expiry. Before starting work, send a heartbeat and wait for it to succeed; only that heartbeat gives a deadline you can rely on.