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, including optional runtime provider and model configuration; 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

--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. It never makes machine_kind writable on an existing agent.

Runtime configuration

schema: 1
machine_kind: daytona
default_model: openai/gpt-5.6-terra
agent:
  name: Support Agent

machine_kind selects the sandbox provider when agent create creates the cloud agent and must be a non-empty string. It is immutable after creation: a local change blocks push, and pull refuses to discard that edit unless --force is used. A cloud-side provider change is reported as pull drift and must be accepted with pull. Create verifies that the control plane honored the requested runtime fields; on mismatch it still claims the manifest with the new agent ID, then exits non-zero so a retry cannot create a duplicate.

default_model is writable. Omit it to leave the field unmanaged, set a model ID to create or update the override, or use default_model: null to explicitly clear it. Non-null IDs are limited to 128 letters, digits, and ., _, -, :, or / characters. Pull writes a reported non-null cloud model, preserves an authored null when the cloud is unset, and keeps authored runtime fields when an older control plane omits them. It refuses to overwrite a local model edit without --force. Push sends a local model edit; if local and cloud both changed, it stops unless agent push --force is used. Push also blocks authored fields that the control plane does not expose. agent status shows push, pull, blocked, unsupported, and conflict states without changing either side.

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.

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.

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.

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