Get Started

Quickstart

This walkthrough takes you from a fresh install to a cloud agent you can pull and push. It assumes you've already installed the CLI.

1. Log in

brainbase login opens the web app and connects this device. The session is stored in ~/.brainbase/auth.json.

bash

brainbase login
brainbase whoami   # confirm who you're signed in as

2. Describe your agent

An agent is declared in a committed brainbase.agent.yaml file — the source of truth for its name, instructions, skills, and MCP servers. brainbase agent init writes a starter one in your project folder. It needs no login and touches nothing in the cloud, so you can run it before step 1 if you prefer.

bash

brainbase agent init            # starter manifest, offline
brainbase agent init --full     # commented template covering every block

Then edit it by hand. A fuller manifest looks like this:

brainbase.agent.yamlyaml

schema: 1
harness: claude-code
machine_kind: daytona
default_model: openai/gpt-5.6-terra
agent:
  name: Repo Assistant
  tagline: Reviews PRs and keeps the changelog tidy
instructions:
  file: ./.brainbase/instructions.md
skills:
  - source: registry:brainbase/changelog@1.0.0
mcp:
  - name: github
    url: https://api.githubcopilot.com/mcp/

Unclaimed vs claimed

A manifest with no id field is unclaimed — it describes an agent the cloud doesn't know about yet. brainbase agent create claims it by creating the cloud agent and stamping the id back into the same file.

Runtime fields are declarative

machine_kind selects the sandbox provider at creation and cannot be changed after the agent exists. default_model is managed on push: omit it to leave the cloud value unmanaged, set a model id to update it, or set it to null to clear the override.

Do not put secrets in YAML

Keep API keys and tokens out of brainbase.agent.yaml, including MCP environment variables and headers. The CLI stores agent secrets in the gitignored .brainbase/secrets.env and syncs them with agent pull and agent push.

3. Create the cloud agent

bash

brainbase agent create   # claims the manifest, stamps in `id`

4. Push and pull

Edit the manifest by hand, then agent push to send local changes up. Use agent pull to bring a teammate's cloud changes down, and agent status to preview both directions before you run either.

bash

brainbase agent status   # what would push, what would pull
brainbase agent push     # send local changes to the cloud
brainbase agent pull     # bring cloud changes into this folder

Schedules belong to orchestrations

Agents do not carry schedules. For a scheduled workflow, define members and schedule triggers in brainbase-orchestration.yaml; a single-agent schedule is an orchestration with one member.

Where to go next

Agents & linking

The full pull / push / unpack lifecycle.

Agent manifest

Every field in brainbase.agent.yaml.

Orchestration manifest

Members, edges, and schedule triggers.

Templates

Pack this agent into something others can install.

Command reference

Every command and flag.