Glossary

Every term below has one meaning in these docs. Where two words name the same thing, the entry says so and the docs use the first.

Session

A piece of long-running work, on its own durable machine (a microVM). A session is not a process and not a conversation: it is the machine plus the records (the two ledgers) that describe the work precisely enough to rebuild it. An agent session holds one or more agents and is worked from the ks app; a plain session runs a program you start and is driven from a terminal with run, attach, exec, checkpoint, fork, wake, kill and meter. The migration commands call a plain session from before agent sessions a legacy session.

ks app

What ks on its own opens at a terminal: a home screen of your agents and, for each agent, a window you stay in (also called interactive mode). Inside an agent’s window, every ks command except agent open, attach, login and logout runs as a / command, with this session and this agent filled in (slash commands).

Agent

A named worker inside an agent session, with its own queue of instructions, its tasks, its results and its runner. A session has a primary agent (usually main) and may have more. A new agent’s state is starting (the client prints “supervised and waiting for its first instruction”); it reads ready after its first instruction.

Runner

The program an agent runs to drive the model. The model is not the runner, and the runner is not KeepState: KeepState supervises it on the session’s own machine and reports what it does. Upstream products may call it a harness. Which runners agent sessions support is on Runners.

Instruction and task

An instruction is what you send an agent; the queue holds instructions in the order they were accepted. The commands address an instruction as a task, at every stage (ks task show <task>, ks task cancel <task>). A task has attempts, a state and its results. An agent’s own “done” is a report: a task reads finished, never verified.

Result and changeset

A result is a file a task produced, verified against its recorded sha256 on receipt and before it is served. Every attempt also records a changeset: what it changed against the base it started from, which ks result apply applies only onto that base.

Checkpoint and save

A checkpoint is the whole machine saved at one moment: its memory, its disk and its device state, written as one unit or not at all. To save is to take one: ks checkpoint (alias save) in a plain session; pausing, or the checkpoint policy, in an agent session. What is inside the boundary and what is not: architecture.

Pause and parked

To pause a session is to save it and stop its machine: session time stops, and only storage is billed. The state the client then shows is parked (Paused, in the browser console). A session is also paused when it is idle for its idle period and when the account’s credit runs out (usage and costs).

Resume, wake and the other resumes

To resume a paused session is to rebuild its machine from its checkpoint and continue. Five commands resume something, and they are different:

Restore

Taking an agent session back to a named checkpoint: ks session restore --checkpoint, which says first what continues from it and never picks the checkpoint for you.

Fork

Branching a checkpoint into new sessions, each with its own lineage, its own writable disk and its own network. In an agent session, ks session fork starts as a plan and is carried out by the plan’s digest; in a plain session, ks fork. Forking needs a paid plan. ks fork --steer gives each branch of a plain session its own text for its next model call, added by the gateway and never written into the machine (gate 5).

Lineage and the two ledgers

A session has one history, recorded twice: the host event log and the transcript inside the machine, reconciled by sequence numbers. On resume the reconciliation happens, and is recorded, before the program wakes (gate 3). A fork starts a new lineage whose log begins with a record naming its parent and the point it branched from. More in sessions and the two ledgers.

Permission request (also called approval)

An agent’s request to run one exact action, which waits for your decision. A decision is compared with the action as it was shown to you, and an allow is for that one action (approvals and control).

Controller (control lease)

The one window that steers an agent. It holds a renewable control lease; any other window watches. Taking control is an explicit act, and an instruction sent from a window that lost control is refused.

Adviser

An agent another of your agents may consult, over a connection you made, which is limited and which you can withdraw: one question, one attributed reply that authorizes nothing (advisers).

Budget and credit

Two different stops. A session’s budget is the number of model tokens the gateway lets its machine use. Your account’s credit pays for session time and storage. See usage and costs.

KV cache

The attention cache a model provider keeps on its own servers while serving a conversation. It lives outside the machine, so a checkpoint does not and cannot contain it. What a checkpoint does preserve is the machine’s own copy of the conversation: the agent’s process memory, its transcript as the runner stores it, its files. On resume the runner sends its context again, as it always does. These docs say “process memory” and never “model memory”.

Provider

The company whose API serves the model. Every call leaves through the gateway. Which routes are available, and their scope, is in how sessions run.

Gateway

The metering proxy every model call from a session’s machine passes through. It resolves your key when a call leaves (the machine only ever holds a per-session credential), stamps every response with a sequence number, enforces the session’s token budget and meters the calls.

Replay

What the gateway does with a call interrupted by a save: it serves the completed response from its store when the program retries, so the call is bought once. It is not a command you type. See architecture.

Warm and cold resume

A resume is warm when the checkpoint’s chunks are already on the host that resumes it, and cold when they must be fetched first. On the fleet, 25.1 seconds warm and 47.5 seconds cold at the 95th percentile (rs-1). The age of a checkpoint does not make a resume colder.

Manifest

The index that says what a thing is made of. A checkpoint manifest lists the chunks a checkpoint restores from, so a restore either has every chunk the manifest names or refuses. An acceptance manifest is what a Cruise job locks when you approve it: the checks, the model ladder, the spend ceiling, and the paths the agent may change.

Cruise job, ladder and rung

A Cruise job is one bounded coding task with its own tests. Its ladder is the list of models it tries, cheapest first; each model on it is a rung. Every rung starts from the same checkpoint, and a result is accepted by the tests, not by any model’s word (Cruise).

Independent verifier

What checks a Cruise candidate against the approved tests. It runs outside the agent’s reach, after the candidate is extracted and the agent’s machine is stopped, and does not trust the agent’s own report. It does not promise that the tests cover every possible defect.

Verdict receipt

The signed record of a Cruise verdict: which tests ran, by digest, and whether they passed (Cruise).

Cruise proposal

A Cruise job an agent proposes by leaving its manifest among a task’s results. Nothing runs until you approve that exact manifest by its digest.

Migration

Turning a plain session into an agent session, through a preview you review and confirm by digest, with a checkpoint to roll back to (Runners).

Evidence bench

The aarch64 machine the founding tests ran on. When a number says “on the bench”, it means this machine, not the fleet your sessions run on. It is not something you build or use; see the evidence bench and, for which kind of measurement a number is, the methodology page.

Plug-pull (kill-and-resume)

A running machine and the daemon supervising it are killed together, mid-task, and the session resumes from its last checkpoint in the same state. The recorded one took 25.2 seconds from the kill to the agent visibly back at work (the demo report).

Gate

A scripted test with a stated hypothesis, a timeout, cleanup, and a sabotage mode that must fail correctly before a pass counts. A claim on this site cites the dated test that supports it, with its outcome, scope and limitations in a public summary (Proof).

Both arms

The two model families a Cruise ladder can run on, each tested the same way: a cheap model first, and a stronger one from the same checkpoint when the cheap attempt fails its tests (Cruise).