Run durable AI agent sessions in microVMs that can be checkpointed, paused, and resumed with all memory and processes intact.
Also known as Keepstateai/cli, cli, @keepstateai/cli
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.1.44
- Last commit
- Nov 14, 2026
- License
- MIT
What is KeepState MCP?
KeepState runs durable AI agent sessions in microVMs that can be checkpointed, paused, and resumed with all memory and processes intact.
Summary generated from the project's README
About KeepState MCP server
KeepState provides a way to run durable AI agent sessions within microVMs. This system allows developers to checkpoint, pause, and resume agent sessions so that memory, files, and running processes remain intact. Users interact with the service through the ks CLI, which connects to a remote control plane. After performing a browser-based login, developers can use commands like run, checkpoint, and wake to manage their sessions on the fleet.
The platform also features a Cruise job system designed for goal-oriented tasks. A Cruise job uses a ladder of models to attempt a goal, verifying each attempt with a check such as pytest, npm test, or go test. The system ensures that a candidate is only accepted when a verifier confirms the result. Users can manage these jobs with commands to check status, view logs, or retrieve a verified artifact tarball. The CLI includes safety limits, such as a default 50 MiB workspace limit and a $2 spend ceiling per attempt.
What you can do with it
- 1Resume interrupted agent sessionsA developer can stop a running agent and restart it later with all its memory and processes preserved.
- 2Automate goal-oriented model testingYou can initiate a Cruise job to have a ladder of models attempt to reach a specific goal like passing inventory tests.
- 3Retrieve verified workspace artifactsOnce a job is successfully completed and verified, you can download the resulting tarball.
Written from the project's README. Every use case is checked against a quote from it.
How to install KeepState MCP
Formats verified 10 Nov 2026Install KeepState MCP in Claude Code
$ claude mcp add cli -- npx -y @keepstateai/cliInstall KeepState MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"cli": {
"command": "npx",
"args": [
"-y",
"@keepstateai/cli"
]
}
}
}Install KeepState MCP in VS Code
.vscode/mcp.json
{
"servers": {
"cli": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@keepstateai/cli"
]
}
}
}Install KeepState MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"cli": {
"command": "npx",
"args": [
"-y",
"@keepstateai/cli"
]
}
}
}Install KeepState MCP in Codex
~/.codex/config.toml
[mcp_servers.cli] command = "npx" args = ["-y", "@keepstateai/cli"]
Install KeepState MCP in Gemini CLI
~/.gemini/settings.json
{
"mcpServers": {
"cli": {
"command": "npx",
"args": [
"-y",
"@keepstateai/cli"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablekeepstateai/cli is public and reachablegithub.com/keepstateai/cli ↗Pass
- Package names this repository as its source@keepstateai/cli names keepstateai/cli as sourcenpmjs.com/package/@keepstateai/cli ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @keepstateai/clinpmjs.com/package/@keepstateai/cli/v/0.1.44#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-14github.com/keepstateai/cli ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @keepstateai/cliPass
- No critical advisory in the package or its dependenciesthe package checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubks — the KeepState CLI
Durable agent sessions: run an AI agent in a microVM, checkpoint it, kill it, wake it — and it resumes mid-sentence, files, memory, and running processes intact.
This is the thin client. Every verb terminates at the KeepState control plane; the client is a key, the building is keepstate.ai.
Install (any one of three)
curl -fsSL https://keepstate.ai/install.sh | sh
brew install keepstateai/tap/ks
npm install -g @keepstateai/cli
Every path downloads the same public-CI-built binary and verifies its
SHA256 against the release's SHA256SUMS before installing. Releases
carry GitHub build-provenance attestations.
Three commands to a session
ks login # browser device flow
ks run # a durable session on the fleet
ks checkpoint <id> --stop && ks wake <id> # the plug-pull, survived
ks doctor checks connectivity, token, and version. ks update
self-updates (checksum-verified; a mismatch is refused).
Cruise
A Cruise job is a goal, a check and a ladder of models. The fleet runs one attempt per rung from an exact save point, verifies the candidate in a verifier the agent cannot reach, and accepts only when the check passes. A failed rung escalates to the next one; after the last rung the job waits in your review queue. Nothing is accepted on a model's word.
ks cruise init --goal "make the inventory tests pass" # drafts .keepstate/cruise.json
ks cruise approve # locks it: .keepstate/cruise.lock
ks cruise run # uploads the workspace, starts the job
ks cruise status # rung, attempts, save points, spend, verdict
ks cruise artifact <job> # the accepted tarball, sha256-verified
ks cruise receipt <job> # the signed receipt, exactly as sealed
ks cruise verify receipt.json # the receipt's signature, checked offline
init reads the repository: the check is the test command it finds
(pytest, npm test, go test) or the one you name with --tests. A
goal with no check is not a job; init stops and says so. It makes no
request and never calls a model. approve records the manifest's digest;
run refuses a draft that is not approved, a test or workspace changed
since approve, and a workspace over 50 MiB (.git and .keepstate
excluded). Defaults: 1800 s per attempt and a $2 spend ceiling
(--spend); the ladder comes from the model table (ks cruise models,
--ladder family:model,...). ks cruise logs, cancel and resume
complete the set. Every --help makes no request.
ks cruise verify RECEIPT checks a receipt's Ed25519 signature against the
public key list KeepState publishes (--keys-url, or a saved copy with
--keys-file, which makes no request at all), with no sign-in and no service
key; the receipt is never sent anywhere. Exit 0: verified under a key that was
valid at the receipt's time. Exit 1: not verified (altered, another key, key
unknown, outside its window or revoked; --trust-before-revocation accepts a
receipt made before its key was revoked). Exit 3: the receipt has no Ed25519
signature, so only the service can check it. Exit 2: unreadable inputs.
Uninstall (one line)
rm -f $(command -v ks) && rm -rf ~/.config/keepstate
MIT licensed.
KeepState MCP questions
How do I add KeepState MCP to Claude Code?
Run claude mcp add cli -- npx -y @keepstateai/cli in your terminal. Add --scope user to make it available in every project.
How do I add KeepState MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How do I start a session?
You can start a durable session on the fleet using the 'ks run' command.
Can I resume a paused agent?
Yes, you can stop a session with a checkpoint and wake it later to resume mid-sentence with files and memory intact.
What is a Cruise job?
A Cruise job is a goal-oriented process that uses a ladder of models to attempt a task, verifying results with a check before accepting them.
How do I check my connection and token status?
Use the 'ks doctor' command to check connectivity, token, and version.