Core Concepts

Agents & linking

An agent is a folder on your machine bound to a cloud agent on the Brainbase platform. The binding is declared in a committed brainbase.agent.yaml manifest; everything else — slug, URL, org/team, and tracking config — is cached in a gitignored .brainbase/state.json.

Claimed vs unclaimed

A manifest with no `id` is unclaimed: it describes an agent you want but the cloud doesn't know about yet. brainbase agent create claims it by creating the cloud agent and writing the id back into the same file. Once id is set the manifest is claimed, and pull / push / unpack operate on that exact cloud agent.

The lifecycle

Command	What it does
`agent create`	Claim an unclaimed manifest and create the cloud agent.
`agent push`	Send local manifest changes (instructions, skills, MCPs, playbooks) to the cloud.
`agent pull [<id>]`	Bring cloud changes into this folder.
`agent pull --run-entrypoint`	Pull, then execute the agent's declared entrypoint (see below).
`agent status`	Preview what would push and what would pull.
`agent unpack`	Install the claimed agent into a harness layout (CLAUDE.md, .claude/, etc.).
`agent env`	Print export lines for `eval $(brainbase agent env)`.

--force applies to both pull and push: on pull it overrides local edits with the cloud copy, and on push it overwrites the cloud copy with your local changes.

The entrypoint

A manifest can declare an entrypoint — a startup routine expressed as a file, a list of commands, or inline text. agent pull resolves it into .brainbase/entrypoint.sh. By default it is only written, not run; pass --run-entrypoint (or set BRAINBASE_RUN_ENTRYPOINT=1) to execute it as part of the pull, with output captured to .brainbase/entrypoint.log.

bash

brainbase agent pull --run-entrypoint    # pull, then run the entrypoint
BRAINBASE_RUN_ENTRYPOINT=1 brainbase agent pull   # same, via env

Linking an existing agent

To attach the current folder to an agent that already exists in the cloud, use link instead of create. It's interactive by default; pass --agent <id> to attach non-interactively, and --no-tracking to skip routing LLM traffic through Brainbase.

bash

brainbase link                       # interactive
brainbase link --agent <id> --yes    # non-interactive
brainbase status                     # show what this folder is linked to
brainbase unlink                     # disconnect this folder

Secrets and run

The agent's secrets live in .brainbase/secrets.env (gitignored). agent pull writes the file; agent push and brainbase run read it. agent env emits shell export lines from it so you can load them into your current shell, and run wraps a child command with .brainbase/secrets.env loaded into its environment — handy for running the agent's own tooling locally without leaking credentials into your shell history.

bash

eval $(brainbase agent env)          # load secrets into this shell
brainbase run npm test               # run a command with secrets loaded

Where state lives

The committed manifest holds declarative content. Cached cloud metadata and per-checkout sync state live under .brainbase/ (gitignored). See Files & state for the full layout.