Profile Schema

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

Current Support

Sandbox SDK backends: OpenCode, Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, NanoClaw, ACP, Cursor, and CLI base.
Sandbox UI picker: the current picker exposes OpenCode, Claude Code, Codex, AMP, Factory Droids, Kimi Code, OpenClaw, NanoClaw, Hermes, and CLI base while deferring Pi, Forge, ACP, and Cursor.
Blueprint sidecar: the AI Agent Sandbox blueprint’s current all-harness sidecar advertises Claude Code, Codex, OpenCode, Kimi Code, and Gemini CLI through /api/capabilities.

Products can expose a subset of these lists. Read runtime capabilities from the sandbox or blueprint service instance instead of assuming every harness is enabled. See Sandbox Harnesses.

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

Production policy can block local tool servers.

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
  }
}

Profiles and Policies Integrations