Install

Caplets is pre-1.0. Use the latest CLI and latest docs together.

Required migration when upgrading to 0.26.0 or later

Do not start the upgraded host first. If this host ran caplets@0.25.x or earlier, the one-time legacy-state migration is required after installing caplets@0.26.0 or later and before restarting the daemon, running caplets setup, or serving requests.

Caplets 0.26.0 moved Authoritative Host State into SQL. It does not automatically migrate or fall back to the old backend auth, Vault, remote-security, setup, Operator Activity, or tracked-Caplet stores. Skipping migration can therefore make existing credentials, Vault values and grants, remote clients, setup history, activity, and tracked Caplets appear missing.

Stop every Caplets Host Node, back up the legacy state roots and configured SQL database, then verify and run the migration:

caplets storage migrate-legacy --dry-run
caplets storage migrate-legacy
caplets storage status --json

Resolve every dry-run error before running the write migration. Record the backup path printed by the migration, and restart the host only after storage status reports ready. Fresh hosts that never ran a version before 0.26.0 do not need this migration. See Authoritative Host State for default paths, custom-path guidance, backup requirements, and recovery behavior.

Requirements

• Node.js 22 or newer for published packages.
• An agent that can use MCP, such as Codex or Claude, or a native integration such as OpenCode or Pi.

Install

Use npx if you only want to try a command without installing globally:

npx caplets install spiritledsoftware/caplets osv

Use the global CLI before running setup. Setup installs or reuses the local Caplets daemon and writes agent configuration that launches caplets attach <local-daemon-url>, so the binary needs to stay on your PATH:

npm install -g caplets
caplets setup
caplets install spiritledsoftware/caplets osv

caplets setup configures supported agent harnesses. It initializes user config, health-checks the daemon before writing agent config, and uses daemon-backed attach/native clients so backend execution keeps the full Caplets environment. The OSV Caplet is the recommended first install because it is public and does not require credentials.

Open the dashboard

If you start or expose an HTTP runtime, the same Current Host serves the browser administration surface at fixed /dashboard:

http://127.0.0.1:5387/dashboard
https://caplets.example.com/dashboard

Current Host protocol namespaces are origin-root paths. A reverse proxy must expose them directly; prefix-only hosting is unsupported.

Use the dashboard when you need an Operator session for host administration rather than an Access session for agent/runtime use. Browser approval uses the same host-side remote credential state as CLI approval. See Dashboard for the full operator flow.

Install lockfiles and updates

Successful installs write a lockfile so the same Caplets can be restored or updated later. Project installs write ./.caplets.lock.json. Global installs write caplets.lock.json under the Caplets state directory, such as ~/.local/state/caplets/caplets.lock.json on Linux.

Restore the Caplets recorded in the selected lockfile with no source argument:

caplets install
caplets install --global

Update every tracked Caplet, or only named Caplets:

caplets update
caplets update sentry github

Install, restore, and update refuse to overwrite local edits unless you pass --force. Use --json when a script needs per-entry statuses and machine-readable errors.

For eligible GitHub-shaped external sources, install, restore, and update also attempt best-effort catalog indexing after the local mutation succeeds. Human output prints a short notice when a source may be indexed. JSON output includes per-entry catalogIndexing status values. Eligibility does not verify GitHub repository visibility, and the payload includes the installed CAPLET.md; disable indexing for private repositories or non-public content. Indexing failures never block install/update/restore.

Set CAPLETS_DISABLE_CATALOG_INDEXING=1 to skip catalog indexing network requests entirely.

If an installed Caplet references unresolved Vault values, output includes immediate recovery guidance. JSON rows include vaultSetup with recovery commands; human output prints the relevant caplets vault set or caplets vault access grant command.

For explicit remote catalog lifecycle operations, --remote targets the remote machine’s global Caplets root and global lockfile:

caplets install --remote spiritledsoftware/caplets sentry
caplets install --remote
caplets update --remote sentry

Remote project install and update semantics are intentionally separate from this workflow.

Manual MCP setup

Prefer caplets setup for local MCP clients. It uses the supported MCP-client catalog and configures caplets attach <local-daemon-url> after the daemon is healthy. For an explicit client target, run:

caplets setup mcp-client --client codex

If you need to write a config by hand, keep it daemon-backed and secret-free:

{
  "mcpServers": {
    "caplets": {
      "command": "caplets",
      "args": ["attach", "<local-daemon-url>"]
    }
  }
}

Replace <local-daemon-url> with the loopback daemon URL reported by caplets setup or caplets daemon status; the default is usually http://127.0.0.1:5387/.

For an advanced manual alternative where the agent intentionally launches a foreground process instead of attaching to the daemon, configure caplets serve directly:

{
  "mcpServers": {
    "caplets": {
      "command": "caplets",
      "args": ["serve"]
    }
  }
}

Use npx in the command only for temporary foreground experiments; daemon-backed setup expects a stable installed caplets binary on PATH:

{
  "mcpServers": {
    "caplets": {
      "command": "npx",
      "args": ["--yes", "caplets", "serve"]
    }
  }
}

If you need non-default HTTP serving behavior, prefer user config over repeating flags:

{
  "serve": {
    "port": 5487,
    "path": "/caplets",
    "publicOrigins": ["https://caplets.example.com"]
  }
}

These serve defaults are user-only. They are ignored from .caplets/config.json, do not set transport under serve, and are overridden by command flags and environment variables. A daemon restart picks up changed user defaults for daemon fields that were not explicitly set during daemon install. Local caplets setup still uses a credential-free loopback daemon before writing MCP or native integration config.

Check the install

Run the doctor check after setup:

caplets doctor

If you use npx, run:

npx caplets doctor

The output should show the active Caplets paths and any integration checks Caplets can run in this environment. Treat failed rows as setup work, not as agent bugs.

Anonymous telemetry

Caplets collects opt-out anonymous telemetry for product usage and reliability. The first eligible interactive CLI run writes a notice to stderr only, so JSON stdout and MCP protocol output stay clean.

Disable telemetry for one process:

CAPLETS_DISABLE_TELEMETRY=1 caplets serve

Disable it in your user Caplets config:

caplets telemetry disable

Inspect local state with caplets telemetry status. Caplets never collects raw config, prompts, Code Mode code, tool arguments, tool outputs, logs, file paths, URLs, hostnames, Caplet IDs, credentials, tokens, raw environment variables, raw error messages, or unsanitized stack traces.

First agent check

After doctor is clean enough for your integration, ask the agent:

Use Caplets Code Mode to query OSV for npm react 18.2.0. Return package,
version, vulnerability count, and advisory IDs as compact JSON.

The agent should call the visible caplets__code_mode tool. Inside Code Mode it should use an OSV handle such as caplets.osv, discover the package-version query tool, and return a compact result instead of a full raw payload.

If the agent cannot see caplets__code_mode, restart the agent after caplets setup, then use Troubleshooting.