Configuration

Most configuration surprises come from changing a setting on the wrong machine—or after the process that needs it has started. Begin with ownership, then choose a provider and profiles.

Daemon, runner, and client

The built-in runner shares the daemon’s machine. A standalone runner can execute elsewhere. Neither arrangement makes provider requests local-only: the configured model provider receives the inputs needed for inference.

Trusted process configuration

Each process loads built-in defaults, then ~/.kodelet/config.yaml, then the file named by KODELET_CONFIG_FILE if supplied. Supported environment variables and explicit flags override process settings. KODELET_CONFIG_FILE_MODE=isolated skips the global file, not repository policy.

Client model configuration is not uploaded to the daemon. Use an explicit supported request flag such as --model, or select a daemon-owned profile with --profile, for a new conversation.

Repository configuration

kodelet-config.yaml in the execution directory supplies runner workspace settings, not an override for every global setting. The runner resolves its defaults, repository settings, a selected trusted environment profile, and permitted request restrictions.

A repository cannot set daemon credentials, models, server endpoints, listener/authentication settings, or trusted environment-profile definitions. Runner settings cannot widen trusted host permissions, relax daemon tool or command restrictions, or re-enable daemon-disabled skills or extensions.

Apply changes to the right process

Set API keys and environment variables before starting the daemon or runner that needs them. For a managed local daemon, finish active work and reload configuration with:

kodelet server restart

Restart a standalone runner to change its inherited shell environment, including virtual environments. Repository edits apply to later runs. Stop the local daemon before switching KODELET_CONFIG_FILE or its configuration mode; an already-running daemon does not adopt another terminal’s environment.

Providers and authentication

Provider authentication lets the daemon call a model. Server authentication lets a client connect to Kodelet. These are separate credentials.

API keys

For OpenAI, export the key on the daemon host before the first start:

export OPENAI_API_KEY="your-api-key"
export KODELET_WEAK_MODEL="gpt-5.6-luna"
kodelet server start

Use restart instead of start if a managed daemon already exists: start reuses it. Do not store provider secrets in repository configuration.

For Anthropic, export ANTHROPIC_API_KEY and select an Anthropic model profile, as shown below. If you already have subscription credentials, anthropic_api_access: api-key makes that profile’s intended authentication mode explicit.

OpenAI-compatible services are configured in the daemon’s openai block using base_url, api_key_env_var, and the service’s supported api_mode (responses or chat_completions). Set both the main and weak models to identifiers the service accepts. A compatible endpoint does not necessarily implement every OpenAI feature; the sample configuration includes provider-specific examples.

Subscription sign-in

With a daemon running, connect a Codex account:

kodelet codex login
kodelet codex status

The device sign-in stores provider credentials on the selected daemon. Configure a daemon model profile with provider: openai, openai.platform: codex, and openai.api_mode: responses, then restart and select it. Signing in alone does not switch an OpenAI API profile to Codex.

Anthropic accounts are also daemon-managed:

kodelet anthropic login --alias work
kodelet anthropic accounts list

Select an account through a daemon profile’s account: work and anthropic_api_access: subscription settings; per-query --account is no longer supported. Provider sign-in and account administration require administrator access to the selected server. GitHub Copilot sign-in is available through kodelet copilot-login with an appropriately configured provider profile.

Models and profiles

Use explicit model identifiers instead of relying on defaults that can change between releases. The OpenAI example below selects gpt-5.6-luna as the weak model. Put it in the daemon host’s ~/.kodelet/config.yaml; the optional claude profile demonstrates switching providers:

provider: openai
model: gpt-6-astra
weak_model: gpt-5.6-luna
openai:
  platform: openai
  api_mode: responses

profiles:
  claude:
    provider: anthropic
    model: claude-sonnet-4-6
    weak_model: claude-haiku-4-5-20251001
    anthropic_api_access: api-key

Replace model identifiers if your account requires different ones. Then, on the daemon host:

export ANTHROPIC_API_KEY="your-api-key"
kodelet server restart
kodelet chat --profile claude

Inspect the profiles served by your selected daemon:

kodelet profile list
kodelet profile show claude
kodelet profile current

Named profiles override base settings and inherit omitted fields. Omitting --profile uses the daemon’s active default; --profile default uses base settings without a named profile. default is reserved, not a name to add under profiles.

For new conversations, supported explicit flags can override model settings. Resuming keeps saved model settings and execution context; it is not a way to swap models mid-conversation. After editing profile definitions or defaults, restart the daemon.

Runner profiles and restrictions

Model profiles and runner profiles solve different problems. --profile chooses a daemon model configuration; --runner-profile chooses a runner environment preset. Define environment_profiles in trusted configuration on the runner host—or in daemon configuration for its built-in runner—not in a checked-out repository.

For example, this preset limits the tools and shell commands available for reviewing Git changes:

environment_profiles:
  review:
    allowed_tools: [bash]
    allowed_commands:
      - "git status"
      - "git diff"
      - "git diff *"
      - "git log *"
    skills:
      enabled: false
    extensions:
      enabled: false

Restart the owning process, then start a new conversation with it:

kodelet run --runner-profile review "Review the current Git diff for correctness. Do not make changes."

These settings only narrow the permissions the daemon and runner already permit. They are not an operating-system sandbox or a substitute for isolating untrusted code. Extensions are executable code; install only extensions you trust.

For a single request, you can also disable all model tools or turn off optional capabilities:

kodelet run --no-tools "Explain the difference between a process and a thread."
kodelet run --no-skills --no-extensions "Inspect this repository using the built-in tools."

Server authentication

Local automatic startup uses loopback binding, token authentication, and a built-in runner. Client commands discover its credentials automatically. Public/OIDC and external-runner-only deployments use an explicitly managed kodelet serve process and --server connections.

For an OIDC-enabled server, sign in through its browser approval flow:

kodelet auth login --server https://kodelet.example
kodelet chat --server https://kodelet.example

Replace the example URL with your server. Endpoint selection prefers --server, then KODELET_SERVER, then trusted client configuration, otherwise local discovery. An explicit endpoint never falls back to automatic local execution.

For token authentication, client credentials use --auth-token or KODELET_AUTH_TOKEN; an explicit flag wins over the environment, which wins over saved sign-in state. Runner connections use a separate runner token or enrollment credential. Never pass a runner token to chat, ACP, or an SDK client.

Listener and authentication settings live under serve in trusted daemon configuration. Keep OIDC client secrets in the required owner-only file and static-token configuration private. See the manual’s server setup for the complete deployment options.

OIDC roles gate administration and terminal access, but accepted users share normal chat access. This is not per-user tenant isolation. Use separate deployments and appropriately isolated runners when that boundary matters.