Profiles, code mode, and MCP

A CLI profile is a saved runtime configuration. It selects the agent, session prefix, model policy, tools, code execution policy, reasoning policy, and MCP servers used by a session.

Kestrel creates two profiles by default:

Profile ID	Agent	Purpose
`reference`	`reference-react`	Default local Reference-agent work
`kestrel-one`	`reference-react`	Kestrel One work with its additional tool allowlist

The profile ID is the CLI selection, such as --profile reference. The agent field identifies the runtime implementation. They are related but are not the same identifier.

Minimal custom profile

Profiles are stored in profiles.json under the active Kestrel state root. A custom profile must use the supported reference-react agent:

JSON

{
  "version": 4,
  "profiles": [
    {
      "id": "research",
      "label": "Research",
      "agent": "reference-react",
      "sessionPrefix": "research",
      "default": false
    }
  ]
}

Missing optional fields receive the current defaults during profile loading. Use /profiles and /status to inspect the resolved profile rather than assuming a value from the file alone.

Tools and code mode

toolAllowlist narrows the tools available to the profile. Code mode adds controlled code-execution configuration and its required capabilities. Inspect or change it interactively with:

Text

/code status
/code policy
/code enable
/code disable

Use code mode only when the task needs execution. Filesystem, shell, network, and dependency-install behavior remain governed by the configured sandbox and approval policy.

Reasoning policy

The reasoning field separates provider reasoning requests from retention. live_only is the default retention mode. Provider-visible reasoning can be retained only when explicitly configured, and retained content is encrypted for the configured window. Provider continuation state is not rendered as visible reasoning.

MCP servers

Profiles can expose local or remote MCP servers. The interactive commands cover server discovery, tool inspection, connection configuration, and allowlisting:

Text

/mcp status
/mcp servers
/mcp tools [serverId]
/mcp add stdio <id> <command> [args...]
/mcp add http <id> <url> [--auth-env VAR] [--header-env Name=ENV]
/mcp add sse <id> <url> [--auth-env VAR] [--header-env Name=ENV]
/mcp allow <toolId>
/mcp deny <toolId>
/mcp remove <serverId>
/mcp refresh

MCP authentication values should be referenced through environment variables, not placed directly in a profile committed to source control.

Read CLI terminal client for using a profile in a session and Command suite for platform state locations.