Quickstart

Eight steps: what you need, install and sign in, your key, the app and your first agent, an instruction, a permission request, leaving and coming back, and the results. The outputs quoted below were observed on client v0.1.19 against the production service on 2026-09-30, with identifiers and key suffixes omitted; where this page describes a screen rather than quoting it, it says so.

1 · What you need

macOS or Linux on arm64 or amd64, a KeepState account (signup gives you $10.00 of credit and takes no card), and your own Anthropic API key. The free tier runs one session at a time. Before you start has the full list.

2 · Install and sign in

curl -fsSL keepstate.ai/install.sh | sh
ks login

The installer checks the release’s SHA256SUMS before it installs anything. ks login prints a short code and the URL https://ctl.keepstate.ai/device; you confirm in the browser, and the terminal prints a line naming the account you signed in as. No password passes through the client.

ks doctor

ks doctor (/doctor inside the app) names the account, then prints five ok lines: the control plane is reachable, the token is valid, the service’s capabilities, the protocol, and the client is up to date. Homebrew and npm are on the install page.

3 · Add your provider key

ks key add --provider anthropic

Run this in a terminal, not inside the app: the key is read from standard input, and a / command gets none. You can also add it in the console. One key per provider: adding again replaces it. See keys.

4 · Open the app and start an agent

ks

ks on its own, at a terminal, opens the app. The home screen lists your agents; press n for a new agent session and name the agent (Enter keeps main). The app then:

• uses your enabled Anthropic key (without one it says so, and creates nothing);
• creates the session and its agent, binds the key to it, and starts a machine for the session;
• opens the agent’s window.

anthropic calls go through your key [key ID and suffix omitted]
  create_guest   done: a machine was created for this session
  start_agent    done: the agent's supervisor is running in the machine
agent docscheck is supervised and waiting for its first instruction in session [session ID omitted]

The agent’s state is starting until its first instruction, and ready after it. Session time is billed from this moment until the session is paused or deleted. No model call has been made yet.

5 · Give it an instruction

Type in the input line at the bottom and press Enter. Your message shows at once, marked queued; the agent’s reply and every tool it runs appear above as they happen, and the status line under the input says what the agent is doing.

you    Reply with exactly the word ok, and use no tools.
       queued · task task_…

Esc interrupts the instruction in flight: the agent is asked to stop at a safe boundary, and the window says so until the agent confirms it.

6 · Answer a permission request

When the agent wants to do something that needs your permission, a box appears above the input with exactly what it wants to run: y allows it once, n denies it, d shows the details. The decision applies to the action as it was shown to you; see approvals and control. This step is described, not quoted: the instruction above used no tool.

7 · Leave, and come back

Press Ctrl-C twice on an empty input. The window closes and the agent keeps working on its machine:

left docscheck; it keeps working

Run ks again later and open the agent. The window starts with one line about what happened since you left, then what the agent did:

While you were away (since Sep 30 15:27): 1 instruction finished
docscheck ok
  ● finished (task_…)
● Ready · unchanged 24s · queue 0 · not saved yet · 52 tokens · you control · /help

8 · Look at the results, then clean up

In the agent’s window, /results lists what its tasks produced and /diff <result> shows a changeset against its recorded base. /apply <result> --confirm <digest> applies it to your project, only onto that base; the digest is the one /diff shows. From a terminal in your project directory, ks result apply <result> shows the digest and asks.

Then leave nothing running that you do not want billed. /pause saves the session and pauses it; after that only storage is billed. Or delete the session through a plan:

/session delete --plan
/session delete --execute <plan> --confirm <session>

From a terminal, the same with ks session delete <session> --plan, then --execute <plan> --confirm <session>. The plan says what the deletion removes and whether it erases all of the session’s checkpoint content: content a surviving fork shares stays that fork’s. See usage and costs for what each charge is.

With your first agent working, common workflows covers the everyday jobs, and Cruise adds approved repository checks with an independent verifier: a bounded coding task whose result you apply only once it passes.