Agent manifest
brainbase.agent.yaml is the committed, declarative source of truth for an agent. Edit it by hand, then run brainbase agent push. Cached cloud metadata (slug, URL, org/team, tracking config) lives separately in a gitignored .brainbase/state.json — never in this file.
brainbase.yaml is still read if present, but writes always go to brainbase.agent.yaml.Full example
schema: 1
id: 5ad59580-8028-4c52-9a31-574607a2aacb # present once claimed
harness: claude-code
machine_kind: daytona # selected when the agent is created
default_model: openai/gpt-5.6-terra
agent:
name: Repo Assistant
tagline: Reviews PRs and keeps the changelog tidy
instructions:
file: ./.brainbase/instructions.md
entrypoint:
commands:
- npm install
- npm run build
playbooks:
- title: Release checklist
description: Steps to cut a release
content:
file: ./playbooks/release.md
capabilities:
memory: true
browser: true
slack: false
meeting: false
skills:
- source: registry:brainbase/changelog@^1.0
- source: ./skills/local-linter
mcp:
- name: github
url: https://api.githubcopilot.com/mcp/
is_enabled: true
Top-level fields
schemainteger · 1requiredManifest schema version. Must be 1.
idUUIDoptionalCloud agent id. Absent on an "unclaimed" manifest; brainbase agent create writes it once the cloud agent exists. Its presence is what makes the manifest "claimed".
harnessstringoptionalHarness this agent targets locally: claude-code, codex, or kafka.
machine_kindstringoptionalSandbox provider selected when agent create claims the manifest. Omit it to leave provider selection to the platform. Once the agent exists, the field is immutable: changing it is reported as drift and rejected before cloud writes. Create a new agent to use another provider.
default_modelstring | nulloptionalAgent-level model override managed by the manifest. Omit the field to leave the cloud value unmanaged, set a model id to update it, or set null to explicitly clear the override. Model ids may contain letters, digits, ., _, -, :, and /, up to 128 characters.
agentobjectrequiredAgent metadata. See below.
agent.namestringrequiredDisplay name. Must be non-empty.
agent.taglinestringoptionalShort one-line description.
brainbase.agent.yaml is committed source. Never put API keys, tokens, or other secret values in it, including under MCP env or headers. Agent secrets belong in the gitignored .brainbase/secrets.env; agent pull writes that file and agent push syncs it to the cloud. MCP config may reference those values with placeholders such as ${GITHUB_TOKEN}.instructions
The agent's standing instructions. Set exactly one of file or text — push rejects a block that sets both or neither.
instructions.filestringoptionalPath (relative to the manifest) to a markdown file holding the instructions.
instructions.textstringoptionalInline instructions, as an alternative to file.
entrypoint
Bash that runs inside the sandbox after secrets are loaded and agent pull completes, before the in-VM runner launches. Set exactly one of file, commands, or text.
entrypoint.filestringoptionalPath to a local script; its contents are used verbatim.
entrypoint.commandsarray<string>optionalA list of shell commands. Joined with newlines and prefixed with set -euo pipefail so a failing command fails the boot.
entrypoint.textstringoptionalAn inline script body, used as-is (no fail-fast preamble added).
playbooks
A list of playbooks. Each is shipped as one markdown file with title / description assembled into YAML frontmatter at push time. Defaults to an empty list.
playbooks[].idstringoptionalCloud playbook id. Round-tripped: written by pull and sent back on push so an existing cloud playbook is updated rather than recreated.
playbooks[].titlestringrequiredPlaybook title. Must be non-empty.
playbooks[].descriptionstringoptionalShort description, included in the playbook table.
playbooks[].iconstringoptionalCloud icon for the playbook. Round-tripped between pull and push.
playbooks[].contentobjectrequiredThe body — set exactly one of file or text (same shape as instructions).
skills
A list of skill sources, resolved at agent pull time. Defaults to an empty list. Each entry is { source: <string> }, where source is one of:
| Form | Meaning |
|---|---|
registry:creator/slug | Latest version from the registry. |
registry:creator/slug@1.4.0 | A pinned version. |
registry:creator/slug@^2.0 | A range, resolved at pull time. |
registry:slug | Legacy / unscoped (no creator namespace). |
./relative/path | A local skill directory. |
mcp
A list of MCP servers. Defaults to an empty list. Either url (remote) or command (stdio) must be set; push validates and emits a clear error otherwise.
mcp[].namestringrequiredServer name. Must be non-empty.
mcp[].urlstringoptionalRemote MCP endpoint URL.
mcp[].commandstringoptionalCommand to launch a stdio MCP server.
mcp[].argsarray<string>optionalArguments passed to command.
mcp[].envobjectoptionalEnvironment variables (string → string) for a stdio server.
mcp[].headersobjectoptionalHTTP headers (string → string) for a remote server.
mcp[].is_enabledbooleanoptionalWhether the server is active.
capabilities
Optional toggles that gate the built-in MCP servers when unpack lays the agent into a harness. This block is written by agent pull and read by agent unpack; push never sends it. Omit it to accept the defaults below.
capabilities.memorybooleanoptionalBuilt-in memory MCP server. Defaults to on when absent.
capabilities.browserbooleanoptionalBuilt-in browser MCP server. Defaults to on when absent.
capabilities.slackbooleanoptionalBuilt-in Slack MCP server. Defaults to off when absent.
capabilities.meetingbooleanoptionalBuilt-in meeting MCP server. Defaults to off when absent.
Reserved fields
commands, hooks, and files are accepted by the parser but reserved for future expansion. Listing them today won't break parsing, but push rejects them with a clear message until the server accepts them.
brainbase-orchestration.yaml.