Configuration

Caplets loads user config plus project config. User config is for your personal agent setup. Project config is for capabilities that belong with a repository.

User config

The CLI manages your user config. To inspect or override the active path, use:

caplets config path
CAPLETS_CONFIG=/path/to/caplets.json caplets doctor

CAPLETS_CONFIG is useful in CI, tests, or temporary sessions where you want a different user config file.

HTTP serve defaults

User config can define optional HTTP serve defaults for foreground caplets serve --transport http and the managed local daemon:

{
  "$schema": "https://caplets.dev/config.schema.json",
  "serve": {
    "host": "127.0.0.1",
    "port": 5387,
    "publicOrigins": ["https://caplets.example.com"]
  },
  "mcpServers": {}
}

Precedence is command flags, then environment variables, then user serve config, then built-in defaults. caplets daemon restart re-resolves user serve defaults for daemon fields that were not set explicitly at daemon install time.

serve.publicOrigins entries are full origins, not host-only allowlists. They are used for public request identity such as DNS rebinding checks and remote credential audiences. The config surface intentionally has no transport field under serve; choose transport on the command line.

Keep serve in user config only. Project config ignores serve and warns because project repositories should not control a developer’s local HTTP bind address, auth posture, or public origins.

caplets setup remains safer than a hand-written MCP server. Local setup always prepares a credential-free loopback daemon before writing agent config, even if user serve defaults describe a broader foreground Current Host.

Current Host URL inputs such as CAPLETS_SERVER_URL, upstream URLs, Remote Profile URLs, and native remote selectors are origins: scheme, host, and optional port only. A trailing root slash is normalized away; non-root paths, queries, fragments, and embedded credentials are rejected rather than trimmed. Protocol paths are fixed at the origin root and are not serve configuration.

The dashboard always lives under /dashboard, with its private ceremonies under /dashboard/api/*. A reverse proxy must expose /.well-known/caplets, /api, exact /mcp, and /dashboard at the origin root; prefix-only hosting is unsupported. serve.publicOrigins affects trusted browser request identity, not route placement.

Authoritative Host State

The user config may select the host’s SQLite or PostgreSQL storage backend and optional S3-compatible bundle asset store. Project config cannot override host storage. See Authoritative Host State for schema migration, bootstrap-secret, backup, and legacy-upgrade requirements.

Project config

Project config lives at:

.caplets/config.json

Commit project config when the capability should travel with the repository. Project Markdown Caplet files load by default from the project, while executable backend maps belong in user config.

Schema

Use the canonical public schema URL:

{
  "$schema": "https://caplets.dev/config.schema.json",
  "mcpServers": {}
}

Editors can use https://caplets.dev/config.schema.json for validation and completion.

Exposure

Code Mode is the default exposure. Keep it unless you specifically need visible wrapper tools or direct operation tools for a client that cannot use Code Mode.

{
  "$schema": "https://caplets.dev/config.schema.json",
  "options": {
    "exposure": "code_mode"
  },
  "mcpServers": {}
}

After changing config, run:

caplets doctor

Secret values

Use Caplets Vault for tokens, API keys, private URLs, and other values that should not live in agent config or depend on agent environment propagation.

{
  "mcpServers": {
    "github": {
      "command": "github-mcp",
      "env": {
        "GH_TOKEN": "$vault:GH_TOKEN"
      }
    }
  }
}

After adding a $vault: reference, set the value and grant it to the configured Caplet:

caplets vault set GH_TOKEN --grant github
caplets doctor