Profile Schema

This page documents the profile schema used to configure sidecar agents. The schema is shared across harnesses; each harness maps the fields it supports to its own config files, environment, and runtime flags.

Current Support

• Router-backed harnesses: OpenCode, OpenClaw, NanoClaw, Hermes, AMP, and Factory Droids can accept broad model/provider routing when product policy allows it.
• Vendor-native harnesses: Claude Code, Codex, and Kimi Code map best to their native provider families.
• CLI base: no agent harness; shell and workflow tools only.

Products can expose a subset of this list. Read runtime capabilities from the sandbox or blueprint instance instead of assuming every harness is enabled.

Top-Level Fields

• name: Human-friendly identifier.
• description: Optional detail about what the profile is for.
• extends: Name of a base profile to inherit from.
• harness: Optional agent backend to request when the product allows harness selection.
• model: Primary model to use, in provider/model-id format.
• small_model: Optional secondary model for lighter tasks.
• agent: Map of per-agent overrides (plan, build, explore, or custom).
• permission: Global permission policy (edit, bash, webfetch, tool servers).
• tools: Map of tool names to true or false.
• mcp: Tool server configurations (allowlisted local or remote).
• plugin: Allowlisted plugin names.

Agent Overrides

The agent field is a map keyed by role name. Common keys include plan, build, and explore, but custom names are allowed.

Each agent config can include:

• model: Override model for this agent.
• temperature: Sampling temperature (0.0 to 2.0).
• top_p: Nucleus sampling (0.0 to 1.0).
• prompt: Agent-specific system prompt.
• tools: Per-agent tool enablement map.
• disable: Disable this agent entirely.
• description: Human-readable note about this agent.
• mode: primary, subagent, or all.
• permission: Optional per-agent permission overrides.
• maxSteps: Hard cap on reasoning steps.

Permission Policy

Permissions gate sensitive actions. Each field is one of ask, allow, or deny.

• edit: File edit access.
• bash: Shell access (global or per-command map).
• webfetch: Web access.
• mcp: Tool server access.

Policies can cap permissions (for example, forcing bash to ask), even if the profile requests more.

Tools

The tools map enables or disables individual tools by name. This is the primary way to scope what the sidecar can execute.

Tool Servers (MCP)

The mcp field defines allowlisted tool servers. Each entry is either:

• Local

  • type: local
  • command: array of command arguments
  • environment: optional env map
  • enabled: optional boolean
  • timeout: optional milliseconds

• Remote

  • type: remote
  • url: HTTPS endpoint
  • headers: optional headers map
  • enabled: optional boolean
  • timeout: optional milliseconds

Local tool servers are typically restricted by policy in production environments.

Plugins

The plugin field is an array of allowlisted plugin names. Policies can block plugins entirely.

Inheritance And Merging

If extends is set, the runtime loads the base profile and merges the override fields. Nested objects are merged so you can override only what changes.

Minimal Example

{
  "name": "team-default",
  "extends": "tangle/base",
  "model": "provider/model-id",
  "agent": {
    "plan": { "temperature": 0.2, "maxSteps": 8 },
    "build": { "temperature": 0.1 }
  },
  "permission": {
    "edit": "ask",
    "bash": "ask",
    "webfetch": "allow",
    "mcp": "ask"
  },
  "tools": {
    "git": true,
    "search": true,
    "bash": false
  }
}