Reference

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.

Legacy filename

The older filename brainbase.yaml is still read if present, but writes always go to brainbase.agent.yaml.

Full example

brainbase.agent.yamlyaml

schema: 1
id: agt_1a2b3c4d            # present once the manifest is "claimed"
harness: claude-code
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 · 1required

Manifest schema version. Must be 1.

idstringoptional

Cloud 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".

harnessstringoptional

Harness this agent targets locally: claude-code, codex, or kafka.

agentobjectrequired

Agent metadata. See below.

agent.namestringrequired

Display name. Must be non-empty.

agent.taglinestringoptional

Short one-line description.

instructions

The agent's standing instructions. Set exactly one of file or text — push rejects a block that sets both or neither.

instructions.filestringoptional

Path (relative to the manifest) to a markdown file holding the instructions.

instructions.textstringoptional

Inline 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.filestringoptional

Path to a local script; its contents are used verbatim.

entrypoint.commandsarray<string>optional

A list of shell commands. Joined with newlines and prefixed with set -euo pipefail so a failing command fails the boot.

entrypoint.textstringoptional

An 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[].idstringoptional

Cloud playbook id. Round-tripped: written by pull and sent back on push so an existing cloud playbook is updated rather than recreated.

playbooks[].titlestringrequired

Playbook title. Must be non-empty.

playbooks[].descriptionstringoptional

Short description, included in the playbook table.

playbooks[].iconstringoptional

Cloud icon for the playbook. Round-tripped between pull and push.

playbooks[].contentobjectrequired

The 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[].namestringrequired

Server name. Must be non-empty.

mcp[].urlstringoptional

Remote MCP endpoint URL.

mcp[].commandstringoptional

Command to launch a stdio MCP server.

mcp[].argsarray<string>optional

Arguments passed to command.

mcp[].envobjectoptional

Environment variables (string → string) for a stdio server.

mcp[].headersobjectoptional

HTTP headers (string → string) for a remote server.

mcp[].is_enabledbooleanoptional

Whether 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.memorybooleanoptional

Built-in memory MCP server. Defaults to on when absent.

capabilities.browserbooleanoptional

Built-in browser MCP server. Defaults to on when absent.

capabilities.slackbooleanoptional

Built-in Slack MCP server. Defaults to off when absent.

capabilities.meetingbooleanoptional

Built-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.