Cruise

Cruise takes a bounded coding task with its own tests, tries it on a cheap model, checks the result with a verifier the agent cannot reach, and on a failed check goes back to the exact checkpoint and tries the next model on the ladder. It ends accepted, or in your review queue. This page walks one job through the client; the words it uses for states and verdicts are the ones the client prints. You can also start a job in the browser console, from one of your sessions or from files you upload (section 9), or have the service draft one from your files in a terminal (section 10).

Every step below also runs inside an agent’s window as a / command: /cruise init, /cruise status <job> --watch, /cruise proposal list. Type /cruise logs and /cruise apply in full: /logs and /apply are the agent’s own. A / command never prompts, so where a step asks for a digest, pass it with --confirm <digest>.

1 · What you need

• An account and the client, signed in (ks login).
• Your own provider key for every model family on the ladder (see keys). A job whose ladder names a family you hold no key for is refused at submission, and nothing is billed.
• A repository with a check the client can find: Python tests (test_*.py, *_test.py), Go tests (*_test.go) or Node tests (*.test.js, *.spec.js, test/, __tests__/), at the root or nested.
• Credit on the account. A job bills as the sessions it runs. Each attempt is limited to 1,800 s, and the job stops when its attempts run out. While model costs are unpriced, the spend ceiling you set does not stop a job (see Limits).

ks preflight shows what a run needs and what is missing (your identity, keys, credit, the service’s capabilities, and what an upload would carry) without starting anything.

2 · Draft the acceptance manifest

ks cruise init --goal "make the inventory tests pass"

init looks at the repository, names the check it found, pins the test files by digest, and writes the draft to .keepstate/cruise.json. It makes no request. A repository with no check it can find stops here with exit code 2 and says so: name the check with --check pytest, go or node, or the command that decides done with --tests CMD.

The draft carries the goal, the model ladder (cheapest first), the spend ceiling ($2 unless you pass --spend), the checkpoint policy, and the paths the agent may change and may not (the tests, and the .keepstate/ directory, are always protected).

3 · Approve it

ks cruise preview
ks cruise approve

preview shows what an upload would carry and what it would not, with the reason for each: names and sizes, never contents. Dependency and tool directories the verifier never reads, for example node_modules or .venv, and sensitive or ignored files are left out unless you name them with --allow.

approve locks the draft into .keepstate/cruise.lock and binds into its digest the upload selection, the check and its inputs, and your key for each provider on the ladder. It reads the model catalog and your keys, and starts nothing. A run refuses, sending nothing, if any of the bound inputs changed since. Edit the draft first if the ladder, the ceiling or the allowed paths are not what you want; a changed draft needs a new approve.

4 · Run

ks cruise run

run recomputes the test digest, refuses if a test changed since approve, refuses a workspace over 50 MiB (the client’s limit), packs the repository with what preview listed, uploads it with the locked manifest, and prints the job id. ks cruise run --separate-upload creates the job first and sends the workspace as its own upload; the archive is kept until the upload is stored, so ks cruise upload <job> can send the same bytes again. From here the job runs without you: a paused parent session holds the exact checkpoint, each rung is a fork of it, and every attempt, checkpoint and cost lands on the job’s record.

5 · Follow it

ks cruise status <job> --watch
ks cruise logs <job>

status prints the job’s state (queued, running, verifying, escalating, accepted, review, cancelled or failed), its verdict when it has one (accepted, ladder-exhausted, policy-violation, limit-reached, cancelled), and each attempt with its rung, model, state and cost. With --watch it follows the job live (Ctrl-C ends only the watch). A figure the ledger has not produced reads unavailable, never 0. logs prints the event stream, one event per line.

6 · Apply the result, or decide

ks cruise result <job>
ks cruise apply <job>

result shows an accepted job’s verdict, its provenance and every limitation; --download saves the result, whose digest the client checks before it writes the file (ks cruise artifact <job> --out result.tar.gz downloads the same tarball). apply applies it to your project file by file, only onto the base each file was made from, after showing it and asking for its digest: a changed local file refuses the whole apply and keeps your work.

The verdict is recorded with the approved tests’ digest and a signed receipt (verifier record). It proves that the approved tests passed, and nothing beyond them.

A job that stopped for your decision waits in review:

ks cruise review <job>

When a job moves into review, the service emails the account’s address, where email is set up for the account; the job’s events record whether that email was sent, never the address. review shows why it stopped, every attempt with its exact check result and cost, and each option with its effect. ks cruise resume <job> tries it again from the same paused parent, on the same ladder or on the one --ladder names; ks cruise cancel <job> releases the parent. Resume is refused outside review.

7 · The model table

ks cruise models

The model catalog: the exact model ids, their family, provider route and rung, which runner each is known to work with, where a published rate exists, and whether you hold a key for its provider. A ladder is checked against it before upload and at approve. A job’s cost is what its attempts’ ledger rows say afterwards, never a price computed in advance.

8 · Jobs your agent proposes

An agent can propose a Cruise job while it works: it leaves the job’s manifest among its task’s results, and the service records the proposal. Before your approval, nothing starts, spends or verifies. In the agent’s window:

/cruise proposal list
/cruise proposal show <proposal>

The second prints one in full, with the digest the service states and the digest the client computes.

Approval goes through a draft: the service copies the files of the proposal’s session, drafts the job on the proposal’s terms and computes every digest again from those files, so the digest you approve belongs to the real files, not to the manifest the agent wrote. In the browser console, the session’s page lists its agents’ proposals, each with Review and approve, which opens the console’s flow at its last step. From a terminal:

ks cruise proposal list --session <session>
ks cruise draft create --proposal <proposal>
ks cruise draft approve <draft>

ks cruise proposal approve <proposal> answers with those two steps and creates nothing. Approving the draft approves the proposal, with the job it became, and /cruise proposal decline <proposal> declines it for good. An approved job is its own thing: cancelling the agent’s task, or removing the agent, does not touch it.

9 · Start a job in the browser console

In the browser console, New job on the Jobs page starts a job in five steps, and a session’s page starts one from that session with Start a Cruise job from this session.

1. Source. Files from one of your sessions, running or paused (its whole workspace, or a folder in it), or from your computer: a folder, or a .zip or .tar.gz archive. A folder gets packed in your browser, leaving out .git, node_modules, .venv and other dependency folders, and files with credentials in them, before upload; files your .gitignore ignores drop out after. The job gets a copy, and your session and your folder stay as they were.
2. What we found. What the service found in the copy, as ks cruise init would in a repository: the files the job takes, the ones left out and why, and the check. A file left out can come back in from here.
3. Goal and boundaries. The goal, the paths an attempt may change, and the check.
4. Models and spend. The model ladder, the key for each provider on it, the spend limit, the time each attempt may take and how often it saves. About spending, the console says only this. Token limit is active. Spend limit is in backlog. The spend limit you set goes with the job, without stopping it yet (Limits).
5. Review and approve. The terms in full and their fingerprint: the exact files, the check and the files it reads, the goal, the paths, the models, the key and the limits. Approving starts the job, on terms matching the fingerprint only; any change makes a new fingerprint. The page then moves to the job.

Until approval, the copy of the files serves that job alone, at no charge, and the service deletes it at approval, at discard or when it expires. The Jobs page lists your drafts, the jobs not yet approved. Started in the console or from a terminal, the same files and terms make the same job, with the same digest, followed and applied as in sections 5 and 6.

10 · Drafts the service makes from your files

From a terminal, ks cruise draft create makes the same draft as the console’s flow:

ks cruise draft create --dir . --goal "make the inventory tests pass"
ks cruise draft show <draft> --verify
ks cruise draft approve <draft>

create takes one source:

• --dir <folder>: packed on your machine by the same selection as ks cruise init, and what it leaves out gets named, never sent;
• --archive <file>: a .zip, .tar.gz or .tar archive, sent unchanged;
• --session <session>: the files of one of your sessions, running or paused, copied by the service; --root <folder> takes one folder of its workspace;
• --proposal <proposal>: an agent’s proposal, on its own terms (section 8).

Terms: --goal, --paths, --check, --ladder, --spend and --key; ks cruise draft set <draft> changes them later, and the digest changes with them. ks cruise draft show prints what was read and what was left out, the check, the terms and the digest the client computes from the manifest the service returned; --verify downloads the draft’s archive and computes every digest again. ks cruise draft approve shows the draft and asks for that digest (--confirm <digest> without a terminal), then creates one job from exactly the draft’s files. ks cruise draft list lists your drafts and how long each is kept, and ks cruise draft discard <draft> deletes one with its files.

In an agent’s window, /cruise draft create drafts from that session’s files, since the window fills in its session; draft a folder, an archive or a proposal from a terminal or the console instead.