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,
    "path": "/",
    "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 or self-hosted HTTP runtime.

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