Sakura Configuration Reference

Overview

Sakura uses a layered configuration system: a TOML file for CLI profiles, JSON files for MCP server connections and team orchestration, and environment variables for secrets and runtime overrides.

1. CLI Configuration — config.toml

The primary CLI configuration file lives at .sakura/config.toml in your project directory. It is created automatically by sakura init.

Sources: src/config.ts

Schema

version = 1
defaultProfile = "default"
maxPlanAgeHours = 4

[profiles.default]
provider = "openai"
model = "gpt-5.2"
temperature = 0.2

[profiles.coding-claude]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
temperature = 0.2

[phase]
language = "typescript"
buildCommand = "pnpm build"
lintCommand = "pnpm lint"
referenceFiles = ["src/types.ts", "src/config.ts"]
projectContext = "A deterministic AI CLI tool"

Top-Level Fields

Profile Fields ([profiles.<name>])

Sources: src/config.ts — ProfileSchema

Phase Fields ([phase])

Used by the /phase scaffold command to drive code generation.

Sources: src/config.ts — PhaseSchema, src/scaffold/phase.ts

Config Resolution Flow

Sources: src/config.ts — ensureInitialized, loadConfig, resolveProvider

2. MCP Server Configuration — mcp.json

Configures external Model Context Protocol servers that Sakura connects to at REPL startup. Tools and resources from these servers are registered into the tool registry and made available to the LLM.

Sources: src/mcp/config.ts, src/mcp/lifecycle.ts, src/mcp/bridge.ts

File Locations (searched in order)

The first file found is used. If neither exists, MCP is disabled silently.

Schema

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@my-org/mcp-server"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      },
      "trustLevel": "trust_read_only"
    },
    "remote-server": {
      "url": "https://mcp.example.com/sse",
      "transport": "sse",
      "trustLevel": "not_trusted"
    }
  }
}

Server Config Fields

Transport Types

Sources: src/mcp/client.ts — createTransport

Trust Levels

MCP tools inherit the trustLevel from their server config. Resources are always registered as trust_read_only.

Sources: src/tools/registry.ts, src/tools/executor.ts

MCP Startup Flow

3. Model Tiers and Provider Defaults

Sakura supports two providers. Each has a default model used when model is omitted from the profile.

Sources: src/providers/openai.ts, src/providers/anthropic.ts

Provider Defaults

Recommended Profile Configurations

Anthropic-Specific Features

Sources: src/providers/anthropic.ts

4. API Provider — Managed Key Mode

When a user is logged in via sakura login, the ApiProvider is used instead of direct provider SDKs. API keys are managed server-side.

Sources: src/providers/api.ts, src/auth/keys.ts, src/auth/session.ts

Key Resolution Order

Sources: src/repl/index.ts — resolveLlmProvider

Auth Storage

Sources: src/auth/session.ts

5. Environment Variables

CLI Environment Variables

Sources: src/providers/api.ts, src/aws/runner.ts, src/auth/keys.ts

API Server Environment Variables

Sources: api/src/services/secrets.ts, api/src/routes/auth.ts, api/.env

SSM Parameter Store (Production)

The API reads secrets from AWS SSM Parameter Store in production. The CLI also checks SSM for API keys before falling back to the API proxy.

Sources: src/repl/index.ts — getKeyFromSsm, api/src/services/secrets.ts

6. Local State Files

Sakura writes runtime state to .sakura/ in the project directory.

Sources: src/planning/store.ts, src/sessions/store.ts, src/mcp/config.ts, src/util/settings.ts, src/auth/session.ts

7. Settings

Runtime settings can be changed