Configuration Reference

This page documents the current implemented schema from src/core/schema/canonical.ts.

It does not describe the future package-first v4 model. For that direction, see Profile Packages.

Envelope

The current canonical profile must use version 3:

version: 3
profile:
  name: mobile-default
  description: Shared mobile engineering setup
  tags:
    - mobile
    - react-native
  created_at: 2026-03-08T00:00:00.000Z
  providers:
    codex:
      enabled: true
    claude:
      enabled: true
    opencode:
      enabled: true
    gemini:
      enabled: false
  instructions:
    global: |
      Keep responses concise.
    project_overrides:
      - ./AGENTS.md
      - ./docs/team-rules.md
  mcp_servers:
    - id: github
      transport: stdio
      command: npx
      args:
        - -y
        - '@modelcontextprotocol/server-github'
      env_refs:
        - GITHUB_TOKEN
      enabled: true
    - id: docs
      transport: http
      url: https://mcp.example.com
      args: []
      env_refs: []
      enabled: false
  skills:
    - id: core-review
      source: local
      path: ./skills/core-review.md
      enabled: true
    - id: security-rules
      source: remote
      path: https://raw.githubusercontent.com/acme/agentstack-skills/main/security.md
      enabled: true
  permissions:
    command_policy: on-request
  provider_overrides:
    codex:
      model: gpt-5
    gemini:
      include_directories:
        - apps/mobile

Top-level fields

Field	Type	Required	Notes
`version`	`3`	Yes	Current canonical version
`profile`	object	Yes	Contains the full profile body

`profile`

Field	Type	Required	Default	Notes
`name`	string	Yes	—	Human-readable profile name
`description`	string	No	—	Optional description
`tags`	string[]	No	—	Optional labels
`created_at`	ISO datetime string	No	—	Optional creation timestamp
`providers`	record	No	`{}`	Enabled providers + provider-local metadata
`instructions`	object	No	empty object	Global instruction fields
`mcp_servers`	array	No	`[]`	MCP server definitions
`skills`	array	No	`[]`	Skill references
`permissions`	object	No	`{ command_policy: on-request }`	Shared execution policy
`provider_overrides`	record	No	`{}`	Provider-specific passthrough values

`profile.providers`

providers is a record keyed by provider id.

Each provider entry must support at least:

Field	Type	Required	Default
`enabled`	boolean	No	`true`

The schema is intentionally permissive here. Extra provider-specific values may be preserved in the provider record or under provider_overrides depending on the import/materialization path.

`profile.instructions`

Field	Type	Required	Default	Notes
`global`	string	No	`""`	Main global instruction text
`project_overrides`	string[]	No	`[]`	Extra project-specific instruction references

`profile.mcp_servers`

Each entry has this shape:

Field	Type	Required	Default	Notes
`id`	string	Yes	—	Stable MCP identifier
`transport`	`stdio \| http`	No	`stdio`	MCP transport type
`command`	string	No	—	Used for `stdio` servers
`args`	string[]	No	`[]`	Command arguments
`url`	string	No	—	Used for `http` servers
`env_refs`	string[]	No	`[]`	Names of env vars required by the MCP
`enabled`	boolean	No	`true`	Enable/disable this MCP

Important:

current schema uses env_refs, not inline env objects
current schema uses an array of MCP objects, not a keyed map by server name

`profile.skills`

Each skill entry has this shape:

Field	Type	Required	Default	Notes
`id`	string	Yes	—	Stable skill id
`source`	`local \| remote`	No	`local`	Where the skill content comes from
`path`	string	Yes	—	Local path or remote URL
`enabled`	boolean	No	`true`	Enable/disable the skill

Important:

current schema uses id, not name
current schema uses path, not an arbitrary source string containing the whole URL/path payload

`profile.permissions`

Field	Type	Required	Default	Notes
`command_policy`	string	No	`on-request`	Shared command approval policy

The schema currently treats command_policy as a string. Providers may materialize it exactly, approximately, or not at all.

`profile.provider_overrides`

provider_overrides is a free-form record for provider-specific passthrough values.

Use it when:

a provider supports native settings that the shared schema does not model yet
imports need to preserve extra fields without losing them
materializers need native-only configuration fragments

Examples already used in the codebase include:

Codex model and personality fields
Gemini include-directories and security fields
raw imported provider settings preserved for round-tripping

What is intentionally not in current v3

The current implemented v3 schema does not contain these top-level fields:

top-level sync
top-level skills
top-level mcp_servers
top-level providers
top-level agents

Those may appear in future package-first work, but they are not part of the implemented schema today.