A local-first agent engine, now with an always-on runtime for macOS

Give your AI
a nervous
system.

Your instructions. Your tools. Your machine. Brainstem Agent, the new experimental runtime for macOS, runs the unchanged Brainstem core inside the macOS sandbox and adds memory, schedules, skills, long tasks, helpers, web and MCP.

Give me my Brainstem How it differs from the core See what works today
  • macOS only
  • Experimental 0.2.0
  • Uses your Brainstem's GitHub Copilot sign-in
  • Inference is remote
  • Not a hosted service
A branching stem connects instructions, tools, and local state into one agent engine.
FIG. 01 / THE CONNECTION BETWEEN INTENT & ACTION
RAPP / BRAINSTEM Check the requirements. Install the core. Add the agent runtime. Start here

01 / CORE VS AGENT

The core you know.
What the agent adds.

What is the same. Brainstem Agent does not replace the core. Both run the same unchanged Brainstem core, the same GitHub Copilot sign-in (from your RAPP Brainstem) and the same model setting. Brainstem Agent runs that core inside sandboxed workers and adds everything around it.

Side by side: the Brainstem core (Grail 0.6.16) on its own, and with Brainstem Agent
AspectThe Brainstem core on its ownWith Brainstem Agent
Who does the thinking The core, through your Copilot sign-in The same unchanged core and sign-in, run in sandboxed workers
Tools out of the box As shipped (0.6.16): memory and Hacker News agents; you can add your own Python agents Files, a sandboxed shell and scripts, background processes, web search and fetch, MCP servers, helpers, schedules and skills
Where tools run Your agents run as you, with your full user permissions In the macOS sandbox: no access to your home folder or your sign-in, writes only in the workspace, and the shell has no network
Long tasks At most three tool rounds per request Continues automatically past three rounds, within set limits, with progress and Ctrl-C to cancel
Always on Runs while its local server runs; you chat in the browser at localhost:7071 A daemon with a warm worker, durable schedules and an inbox, and an optional login LaunchAgent
Memory Remembers across conversations with its memory agent Workspace and profile memory, search across past conversations, correction and forgetting
Proof of work A text log of agent calls A receipt for every tool call (succeeded, failed or uncertain); a request repeated with the same idempotency key replays without a new model call
Ways to use it Browser chat and its local HTTP API A terminal session, an owner-only local web companion, and every command in JSON for other agents
Keeping it running Rerun the installer to update Version manifest, backup, restore and export, upgrade and rollback, uninstall, readiness checks
Platforms macOS, Linux and Windows macOS only (qualified on Apple silicon)

Measured 2026-09-24 on one Mac with Apple silicon

Measured head to head.

How it was measured. Same core, interpreter, Copilot sign-in and model setting on both sides; the core ran as shipped with its own agents; every result was checked on disk and in receipts, not taken from the answer.

What got done.

Four tasks, with the result on each side
TaskCore aloneWith Brainstem AgentDetail
Create a file with given content Not done: no file tool (it said so) Done 2.0 s, one model call
Six-step read-and-write chain Not done: no file tool, and at most three tool rounds Done 11 tool calls over 4 continued segments, 17.7 s
Search the web and cite the page Not done: no web tool (it said so) Done search then fetch, cited the source page, 5.3 s
Remember a fact, recall it in a new conversation Done Done both answered “Teal.”
Total 1 of 4 4 of 4 Neither side claimed an action it did not perform.

What it costs.

Time and memory on each side
MeasureCore aloneWith Brainstem Agent
A warm, trivial turn (median of 10) 0.66 s 0.81 s (+0.15 s: 0.08 s to start the command-line tool, 0.06 s for state, grant and receipts, 0.02 s for the longer prompt)
Memory in use 56 MB (one process) 111 MB (daemon plus sandboxed worker)
Start to ready 0.6 s 1.5 s (a verified warm worker)
One command without the daemon not applicable about 2.0 s (starts and verifies its own sandboxed worker)

Read with care. Small sample on one machine; Copilot latency varies. You can add your own Python agents to the core, but they run with your full permissions and stay within three tool rounds per request.

The same comparison is published as machine-readable JSON. The core stays step 1: install it first.

02 / INSTALL

A terminal away
from your own Brainstem.

Check the requirements first. Then two steps: install RAPP Brainstem, the core, and add Brainstem Agent, the always-on runtime, on your Mac. Each step says how you know it worked.

Before any command

Requirements checklist

  • A Mac for the agent runtime. macOS only, qualified on Apple silicon, with /usr/bin/sandbox-exec, which is built into macOS. On Linux or Windows, step 1 works; stop there.
  • Python 3.11 or newer. The commands use python3.11; Python 3.13 is verified too.
  • Git and internet access. Setup downloads the pinned core, and inference is remote.
  • A GitHub account with Copilot access. You sign in through RAPP Brainstem in step 1. The agent reuses that sign-in, so there is no API key to create.
  • Room for experimental software. Version 0.2.0; interfaces may change. It is not a hosted service.

  1. Step 1 · macOS, Linux or Windows

    Install RAPP Brainstem, the core.

    This is the existing core installer, unchanged. Pick your system, review the installer if you like, and run the command.

    1. Run the installer for your system.
    2. Run brainstem.
    3. Open http://localhost:7071 and complete the GitHub sign-in.

    Done when the GitHub sign-in at http://localhost:7071 is complete. Keep RAPP Brainstem installed: step 2 reuses its sign-in, read-only.

    Choose your operating system

    macOS / Bash

    curl -fsSL https://kody-w.github.io/rapp-installer/install.sh | bash

    Then continue with step 2 on this Mac. Inspect the installer

    Linux / Bash

    curl -fsSL https://kody-w.github.io/rapp-installer/install.sh | bash

    Step 2 needs macOS. On Linux, RAPP Brainstem itself is what you get for now. Inspect the installer

    Windows / PowerShell

    irm https://raw.githubusercontent.com/kody-w/rapp-installer/main/install.ps1 | iex

    Run it in PowerShell. Step 2 needs macOS; on Windows, RAPP Brainstem itself is what you get for now. Inspect the installer

    Existing core installer · Unchanged URLs · Core setup guide

  2. Step 2 · macOS only · Experimental 0.2.0

    Add Brainstem Agent, the always-on runtime.

    Run these in Terminal on your Mac, from the folder where you want the clone. The first four lines clone this repository and install the brainstem-agent command in .venv, a virtual environment inside the clone.

    setup downloads and verifies the pinned core, checking every file against its recorded hash, and builds its private environment. doctor --deep proves the sandbox, worker and sign-in are ready.

    Every command accepts --json: it was built so another AI agent can drive it.

    Done when doctor --deep reports that Brainstem Agent is ready. If it lists a problem, see If something fails.

    macOS / Terminal · install and verify

    git clone https://github.com/kody-w/brainstem-agent.git
cd brainstem-agent
python3.11 -m venv .venv
.venv/bin/pip install ./runtime
.venv/bin/brainstem-agent setup
.venv/bin/brainstem-agent doctor --deep

Then · first run

Put it to work.

Still in the brainstem-agent folder:

  • chat gives it one task, answered through your Copilot sign-in. This one writes notes/hello.txt in the agent's workspace, by default inside ~/.brainstem-agent.
  • serve --detach starts the always-on daemon. It keeps a warm worker and runs your schedules until you stop it; work pauses while the Mac sleeps.
  • status shows the daemon's health, its worker and your schedules. Right after serve --detach the worker may still be starting; a few seconds later it is warm.
  • Optional: service install adds a login LaunchAgent, so the daemon starts when you log in.

macOS / Terminal · first run

.venv/bin/brainstem-agent chat "Create notes/hello.txt containing hi"
.venv/bin/brainstem-agent serve --detach
.venv/bin/brainstem-agent status

Then · every day

Talk to it. Back it up.

Still in the brainstem-agent folder, with the daemon from serve --detach running:

  • open prints a one-time sign-in link for the web companion, which the daemon serves to this Mac only, on 127.0.0.1. Open the link in your browser yourself; nothing opens a browser for you. Each link works once, in one tab.
  • backup --output backups writes a verified snapshot into backups, a new folder here, even while the daemon runs; the folder must be new or empty. Backups are local and unencrypted, and leave out workspace files.
  • version reports the version and the pinned core.
  • The last line, brainstem-agent on its own, opens the interactive terminal session: answers stream as they are written. Type /help for the slash commands; Ctrl-C cancels the running turn and keeps the session; Ctrl-D leaves it. It comes last, so you can paste the whole block: the other three lines run first.

For restore, export, upgrade and rollback, see Operating the cell in the runtime documentation.

macOS / Terminal · every day

.venv/bin/brainstem-agent open
.venv/bin/brainstem-agent backup --output backups
.venv/bin/brainstem-agent version
.venv/bin/brainstem-agent

What it checks

Inside doctor --deep.

doctor runs the first five checks. --deep adds a real probe. If a check fails, doctor says which one and why.

  1. Core source. Every tracked file of the pinned core (Grail 0.6.16) matches its recorded hash.
  2. Private environment. The core worker's own Python environment is installed from a hash lock.
  3. Sign-in. Your RAPP Brainstem's GitHub Copilot sign-in is found. Its value is never shown.
  4. Sandbox. /usr/bin/sandbox-exec works.
  5. Disk and store. There is enough free disk space, and the agent's store, once created, is one this version can read.
  6. Deep probe. A real core worker starts in the sandbox and proves, from inside, that it cannot read your home folder, your sign-in or the agent's state, cannot change the core's files or write outside its own, and can reach no local service except its own broker. Tools answer only to a valid grant, the core's files verify before and after, and the worker's processes are gone once it stops.

Common failures

If something fails.

Not signed in
doctor reports a credential problem: no Copilot credential. Finish step 1: run brainstem, open http://localhost:7071 and complete the GitHub sign-in with an account that has Copilot access. Then run doctor --deep again.
Wrong Python version
python3.11 is not found, or pip refuses the package because it needs a newer Python. Install Python 3.11 or newer. If .venv was made with an older Python, delete the .venv folder and create it again with Python 3.11 or newer (python3.13 works in place of python3.11), then repeat the pip install and setup lines.
Not macOS
The agent runtime does not support Linux or Windows yet: it needs the macOS sandbox and will not run without it. On those systems, use RAPP Brainstem from step 1.
Sandbox unavailable
doctor reports a sandbox problem. The runtime needs /usr/bin/sandbox-exec, built into macOS, and will not run without it. Run the commands directly on the Mac, in Terminal, rather than from inside another sandboxed app or tool, then run doctor --deep again.
“Stop the daemon first”
doctor --deep needs the agent to itself. Run .venv/bin/brainstem-agent stop, run doctor --deep, then start the daemon again with serve --detach.

When you are done

Stop and remove it.

From the brainstem-agent folder, stop ends the daemon and confirms its workers are gone. service uninstall removes the login LaunchAgent if you added one with service install.

To remove it completely, delete the brainstem-agent folder you cloned, including its .venv and any backups folder you wrote there (move a backup out first to keep it), and the runtime's home, ~/.brainstem-agent. The home holds everything the agent saved: the files in its default workspace, state, memory, skills, schedules, conversations and its verified copy of the core. Your RAPP Brainstem in ~/.brainstem is not touched.

macOS / Terminal · stop

.venv/bin/brainstem-agent stop
.venv/bin/brainstem-agent service uninstall

Runtime documentation Report an agent runtime problem

03 / WHAT WORKS TODAY

Six things an agent needs.
Each labelled honestly.

Every card carries its status in Brainstem Agent 0.2.0 and its main limit. The same statuses are published as machine-readable JSON.

  • Available (experimental) Works today; interfaces may change.
  • Partial Works, within the limit shown.
  • In development Being built; not released.
  • Not yet Not available.

  • Deploy

    Partial

    setup downloads and verifies the pinned core and builds a private environment; doctor --deep proves readiness.

    Limit This Mac only; no cloud or remote deployment yet.

  • Always available

    Partial

    serve --detach runs an always-on daemon with a warm worker; service install adds a login LaunchAgent.

    Limit Work pauses while the Mac sleeps; no remote host yet.

  • Schedule

    Available (experimental)

    Ask in plain language or use schedules: one-time, interval and cron, time zones and DST, missed-run and overlap rules, pause, resume, edit, run-now and remove, with results in an inbox.

    Limit Runs only while the daemon is running.

    See the recording

  • Connect

    Not yet

    Messaging apps and email are not connected yet; today you use the terminal or the web companion on this Mac, and tools connect through MCP.

    Limit No messaging channels.

  • Remember

    Available (experimental)

    Workspace and profile memory with correction and forgetting, search across past conversations, and AGENTS.md context files.

    Limit Local to this Mac; retrieval is keyword ranking (BM25), not semantic embeddings.

  • Isolate

    Available (experimental)

    Every core worker, shell command, script and local MCP server runs under the macOS sandbox (Seatbelt) with private per-worker files; tool processes cannot read your home folder or your sign-in and write only inside the workspace; the shell has no network.

    Limit macOS sandbox only; not a VM or container.

Nine more, with the same labels.

  • Learns skills

    Available (experimental)

    Saves how it solved a task as a versioned skill (unreviewed until you approve), offers it in later turns, and lets you review, approve, edit, disable and export it.

    Limit Skills are data offered to the model, never executed and never granting permissions; review is manual.

  • Long tasks

    Available (experimental)

    Continues automatically past the core's three-tool-round limit and streams progress; Ctrl-C cancels and stops the worker.

    Limit Bounded per turn (segments, tool calls, time).

    See the recording

  • Helpers

    Available (experimental)

    Runs up to three helper workers in parallel, each a fresh sandboxed core worker with narrower permissions.

    Limit One level of helpers; bounded count.

    See the recording

  • Tools and processes

    Available (experimental)

    Files, a sandboxed shell, sandboxed Python scripts that call tools, and background processes (start, poll, log, stop).

    Limit Inside the workspace; the shell has no network.

  • Web

    Available (experimental)

    Fetches pages and searches (Wikipedia by default) with citations; private and cloud-metadata addresses are refused; an owner egress policy and log; web content can never make it remember or forget.

    Limit The search provider is Wikipedia unless configured.

  • MCP

    Available (experimental)

    Connects MCP servers (stdio and streamable HTTP) from a JSON config; tools appear as mcp__server__tool; each local server gets its own sandbox profile and permission.

    Limit You add and trust servers yourself.

  • Receipts and recovery

    Available (experimental)

    Every tool call gets a receipt (succeeded, failed or uncertain); repeated requests replay without a new model call; interrupted work is recovered or marked uncertain; backup writes a verified snapshot while the daemon runs and restore checks every digest before writing; export writes skills, memory, profile and sessions in portable formats; upgrade installs a local release side by side and switches back by itself if it does not come up, and rollback returns to the previous version; a rejected sign-in is an explicit state (turns refused, no retries), and signing in again is picked up without a restart.

    Limit Backups are local, unencrypted and started by you, and leave out workspace files; upgrades only from a local checkout, zipapp or wheel (nothing is downloaded); a revoked sign-in can keep working until the core's cached Copilot token expires (about 25 minutes).

  • Terminal session and web companion

    Available (experimental)

    brainstem-agent on its own opens an interactive terminal session (streamed answers, slash commands, Ctrl-C cancels the turn and keeps the session); open prints a one-time link to an owner-only web companion served on 127.0.0.1 (chat, sessions, schedules and inbox, skill review, memory and profile, MCP and the outbound request log).

    Limit This Mac only; each sign-in link works once, in one tab; the terminal is a line session, not a full-screen interface.

    See the commands

  • Browser, images and voice

    Not yet

    No browser automation, image understanding or generation, transcription or speech yet.

04 / RECORDED RUNS

Real runs, recorded.
Not a live demo.

Three runs of the experimental runtime, recorded on 2026-09-23 through real GitHub Copilot inference with the pinned core on macOS (Apple silicon). Prompts and answers are quoted verbatim; an ellipsis marks a trim.

Recorded run 2026-09-23 experimental runtime

One request, four segments, eleven tool calls.

The core allows three tool rounds per request. Brainstem Agent continued on its own until the task was done.

State
succeeded
Segments
4
Tool calls
11
Tools
read_file, write_file
TranscriptNot live

You

Create chain/1.txt containing 1. Then repeatedly read the latest file and write the next file containing the value plus one, up to chain/6.txt. Then report the final value.

Tool log, excerpt

…
[read_file] chain/5.txt (1 bytes):
5
[write_file] Wrote 1 bytes to chain/6.txt.

Answer, verbatim

**Final value: 6** The chain has been created successfully from chain/1.txt through chain/6.txt, with each file containing the value one greater than the previous file.

Recorded run 2026-09-23 experimental runtime

Two helpers, in parallel.

Each helper ran on its own fresh, sandboxed core worker, then the answer joined their results.

State
succeeded
Segments
1
Tool calls
3
Tools
delegate_tasks, read_file
TranscriptNot live

You

Delegate two independent sub-tasks to helpers in parallel: helper A writes par/a.txt containing alpha, helper B writes par/b.txt containing beta. Then tell me both file contents.

Tool log, excerpt

[delegate_tasks] 2 of 2 helpers succeeded (in parallel, …).

Helper 1 (Helper A): succeeded
Done. I've created the file `par/a.txt` with the content `alpha` (no trailing newline).

Helper 2 (Helper B): succeeded
Done. I've written the file `par/b.txt` with the content 'beta' (no trailing newline).
…

Answer, verbatim

Done! Here are the file contents: - **par/a.txt**: `alpha` - **par/b.txt**: `beta` Both files were created in parallel by the helpers as requested.

Recorded run 2026-09-23 experimental runtime

A schedule, in plain language.

The first call asked for something a schedule may not hold and was refused. The retry created a one-time schedule holding only the shell capability.

State
succeeded
Tool calls
2
Tools
schedule_create
TranscriptNot live

You

In 1 minute, write the current time into notes/time.txt.

Tool log, excerpt

[schedule_create] A schedule may only hold capabilities from ['files.read', 'files.write', 'memory.read', 'memory.write', 'shell.run', 'schedule.read', 'schedule.write']; refused: ['run_command'].
[schedule_create] Created schedule … with capabilities ['shell.run'].

Answer, verbatim

Done! I've scheduled a task to write the current time to notes/time.txt in 1 minute (at 2026-09-23T04:40:38).

05 / HONEST LIMITS

What it needs.
What it isn't, yet.

Brainstem Agent is experimental. Read this before you rely on it.

It needs

  • macOS only. Qualified on Apple silicon, using /usr/bin/sandbox-exec, which is built into macOS. On Linux and Windows the core installer works; the agent runtime does not yet.
  • Python 3.11 or newer, Git and internet access. Verified on Python 3.11 and 3.13.
  • A GitHub Copilot sign-in through your Brainstem. RAPP Brainstem installed and signed in with a GitHub account that has Copilot access. The agent reuses that sign-in read-only; there is no separate API key.

Know this

  • Experimental, version 0.2.0. Interfaces may change.
  • Inference is remote. Prompts, conversation context and tool results used for inference leave your Mac. Web tools contact the sites you ask about.
  • Work pauses while the Mac sleeps. Schedules run only while the daemon is running.
  • Not a hosted service. It runs on this Mac only; there is no cloud or remote deployment yet.
  • Not yet: messaging channels, cloud or remote hosting, browser automation, images and voice, and encrypted, scheduled or off-machine backups.
  • The core stays unchanged. Grail is never modified or redistributed; setup downloads the pinned public source and verifies every file.

06 / HOW IT WORKS

An unchanged core.
A cell around it.

Brainstem Agent runs the unchanged Brainstem Grail core, the stable core edition, inside private sandboxed workers, and adds everything around it: sandbox, memory, schedules, tools, helpers, web and MCP. Grail is never modified or redistributed. Setup downloads the pinned public source and checks every file's hash before use.

  • Mitochondrion The Grail core: the cell's unchanged power source.
  • Membrane The macOS sandbox around every core worker and tool process.
  • Nucleus State and memory, kept on your Mac.
  • Organs The tools: files, shell, scripts, web and MCP.
FIG. 02 / A CELL AROUND AN UNCHANGED CORE
Core
Brainstem Grail 0.6.16
Source
kody-w/rapp-installer
Commit
49db80c8c6b6caa7647369beaf477d374a8f293c
Kernel SHA-256
bd55a7f0bcf5efd3f7966ca39bb146da3c25fda9a0b1ce5ba587919d3c3775f4
Inference
Through your RAPP Brainstem's GitHub Copilot sign-in, reused read-only. Model choice: that connection only, by design.

07 / QUESTIONS

A little clarity
goes a long way.

How are RAPP Brainstem and Brainstem Agent different?

RAPP Brainstem is the product and its core engine, which step 1 installs, with a local server and a browser chat. Brainstem Agent is the experimental always-on runtime in this repository, run with the brainstem-agent command. It runs the Brainstem Grail core unchanged inside the macOS sandbox and adds memory, schedules, skills, long tasks, helpers, tools, web and MCP.

Do I still need the Brainstem core?

Yes. The core is step 1: Brainstem Agent runs the same unchanged Brainstem core and uses the GitHub Copilot sign-in of your installed RAPP Brainstem. On Linux and Windows, the core on its own remains the choice, because Brainstem Agent is macOS only. See how the two differ.

Why install the core first if setup downloads it?

Brainstem Agent runs its own pinned, verified copy of the core, but it signs in through your installed RAPP Brainstem: it reuses that GitHub Copilot sign-in, read-only. That is why there is no separate API key.

What account do I need?

A GitHub account with Copilot access, signed in through RAPP Brainstem. Model choice is that GitHub Copilot connection only, by design.

What leaves my Mac?

Prompts, conversation context and tool results used for inference go to the remote model through your Copilot sign-in, including file contents a tool has read. Web tools contact the sites you ask about. The agent's state, memory and schedules are stored on the Mac, by default in ~/.brainstem-agent.

Does it work on Linux or Windows?

The RAPP Brainstem core installer supports them. The agent runtime does not yet: it is macOS only, qualified on Apple silicon, because it depends on the macOS sandbox.

What happens while my Mac sleeps?

Work pauses. Schedules run only while the daemon is running; their missed-run and overlap rules decide what happens to runs that came due in the meantime. It is not a hosted service, and there is no remote host yet.

Can another AI agent drive it?

Yes. Every command accepts --json; it was built so another AI agent can drive it from a terminal. The capability statuses on this page are also published as JSON.

Where can I get help?

Read the runtime documentation and report agent runtime problems in the Brainstem Agent issues. For the core installer and sign-in, use the core setup guide and the core issues. To stop or remove the agent runtime, see Stop and remove it.

YOUR MACHINE. YOUR DIRECTION.

Every great idea
needs a way to act.

Give me my Brainstem

Start with the core. Add the agent runtime on your Mac.