Caimeo Brainstack

Brainstack

Shared memory and operational context for AI agents running on your own machines. Brainstack turns a git-backed brain into searchable, reusable context for Codex, Claude, Cursor, scripts, Telegram, and private workers.

See how it works Deploy Brainstack
Brainstack product view showing brainctl doctor output, shared-brain search results, worker status, and a private tailnet status line.
Simulated product view Brainstack operator view with doctor output, shared-brain search, worker status, and private tailnet state.

Brainstack product view with an operator panel, a shared-brain repo and search service, optional telemux, three tailnet workers, doctor output, search results for runbooks, and worker status rows.

What it is

A private shared brain for tools and machines

Brainstack gives agent tools a durable place to remember what happened, save useful context, and find it again. The source of truth is a git repo with markdown, skills, transcripts, and artifacts. Brainstack adds local search, write paths, health checks, client bootstrap, optional Telegram control, file relay, and worker routing.

Product code and brain data stay separate

The Brainstack repo contains the services and CLI. Your shared brain remains its own repo. That split matters: upgrades can refresh services and runtime files without rewriting the knowledge base your tools depend on.

  • braindLocal service that lets tools search and read the shared brain.
  • brainctlCLI for provisioning, enrollment, health checks, backups, recovery, and file relay.
  • client bootstrapCodex gets installable Brainstack skills; Claude and Cursor get checked-in shared-brain guidance.
  • telemuxOptional Telegram topics mapped to durable work contexts and file delivery.

How it works

Three simple pieces

1

Git is the memory

Everything you store, from LLM chat transcripts to markdown pages, skills, notes, and artifacts, lives in the shared-brain repo and feeds fast local search.

2

Tools share the same context

Codex, Claude, Cursor, and scripts can all read the same memory instead of each tool starting over with its own scattered notes.

3

Your machines do the work

Run jobs on your own Mac, Linux box, or private tailnet workers. Telegram is optional; it is just a phone-friendly control surface.

Deploy

Start with the shared brain, then add machines

The core Brainstack path is a private control host running braind over a shared-brain repo. After that, brainctl can enroll Mac or Linux clients, bootstrap harness instructions, check workers, and optionally connect Telegram through telemux.

1. Stand up Brainstack Install braind on a private control host tied to the shared-brain repo. 2. Enroll clients Add client machines; the Mac binary path avoids Bun and source checkout. 3. Add control surfaces Enable Telegram topics, file relay, and workers only when they are useful.
Before you start: The control host needs Bun, Git, OpenSSH, Tailscale, a selected harness, and the shared-brain repo. Client machines need Git, SSH, Tailscale, and the harness they will run. macOS clients can use the compiled brainctl installer without Bun or a Brainstack source checkout; Linux clients follow the fresh-machine/source-run path for now. Read the fresh-machine guide and the Mac client quickstart for the full flow.

1. Generate control-host config

git clone https://github.com/Caimeo-com/brainstack ~/brainstack
cd ~/brainstack
bun install --frozen-lockfile
bun run packages/brainctl/src/main.ts provision \
  --profile single-node \
  --out ~/.config/brainstack/brainstack.yaml \
  --harness codex

2. Smoke-test, install, verify

bun run packages/brainctl/src/main.ts smoke \
  --profile single-node \
  --config ~/.config/brainstack/brainstack.yaml

less ~/.config/brainstack/brainstack.yaml
bun run packages/brainctl/src/main.ts init \
  --profile single-node \
  --config ~/.config/brainstack/brainstack.yaml
systemctl --user daemon-reload
systemctl --user enable --now braind.service
loginctl enable-linger "$USER"

bun run packages/brainctl/src/main.ts doctor \
  --config ~/.config/brainstack/brainstack.yaml
What this gives you: A private shared-brain service, a versioned CLI, deterministic runtime files, and a doctor baseline before clients, Telegram topics, or remote workers are added.
Brainstack control-host install workflow screen with four panels: generate config, smoke-test config, review and install, verify and activate.
Simulated product view Control-host setup flow for Brainstack admins building braind and runtime services.

Control-host install screen showing the high-level service setup flow: generate config, smoke-test the generated config, review and install user services, verify health, and activate later runtime updates.

Enroll client machines

Create a private invite on the control host, then hand the bs1_... value to the client operator over a private channel. The invite can carry shared-brain config, an optional import token, pinned SSH host keys, and control-host details for file relay. macOS gets the lowest-friction binary path; Linux clients can use the same config model through the fresh-machine/source-run path.

Create the invite

brainctl invite create \
  --config ~/.config/brainstack/brainstack.yaml \
  --import-token-file ~/brain-import-token.txt \
  --control-ssh operator@brain-control \
  --ssh-known-hosts-file ~/.config/brainstack/control_ssh_known_hosts \
  --control-repo ~/brainstack

On macOS, install brainctl and enroll

# After your operator publishes a Brainstack release:
BASE=https://github.com/Caimeo-com/brainstack
RELEASE_TAG=vX.Y.Z
REL="releases/download/$RELEASE_TAG/install.sh"
curl -fsSL "$BASE/$REL" | sh

# Paste the bs1_... invite your operator gave you.

Verify any enrolled client

brainctl doctor --config ~/.config/brainstack/brainstack.yaml

Optional Codex skills

brainctl skills install --target codex --profile client

Optional: Telegram control and file relay

When telemux is enabled on the control host and a Telegram control chat or context exists, enrolled machines can stream files to telemux and receive them in Telegram without storing Telegram bot secrets locally. Telegram is a control surface on top of Brainstack, not a requirement for the shared brain.

Enable telemux on the control host

# After enabling telemux in brainstack.yaml:
bun run packages/brainctl/src/main.ts apply-runtime \
  --config ~/.config/brainstack/brainstack.yaml
vi ~/.config/brainstack/telemux.secrets.env
systemctl --user enable --now telemux.service

Send a file from an enrolled machine

brainctl telegram send-file \
  --config ~/.config/brainstack/brainstack.yaml \
  --file ~/Downloads/report.pdf \
  --caption "Report from my machine"

Trust boundary

Private first, explicit when dangerous

Brainstack is for trusted private machines. In trusted-tailnet mode, anyone who can reach braind on the private mesh is trusted to read the brain. Tailnet routing, grants, and firewall policy are the read boundary.

Start without Telegram The shared-brain service and brainctl work without telemux. Add Telegram only if remote topic control is worth the extra authority.
Restrict the control user Telemux accepts messages only from the configured Telegram user. Keep the bot token private and treat compromise as a visibility and disruption risk.
Know what yolo mode means If Codex or Claude can run unattended, Telegram becomes a remote path into that harness. Passwordless sudo raises that authority again.
Keep workers on the tailnet Use normal OpenSSH over Tailscale, pinned host keys, and doctor --workers before dispatching jobs.
Keep bot secrets on control Client file send uses SSH to reach telemux. Telegram provider credentials stay on the control host, not on every enrolled machine.

Telegram control

A topic becomes a durable work context and file drop

Bind a Telegram topic to a host, scratch space, or repo. After that, messages from the allowed user can resume the stored Codex or Claude session, and enrolled machines can send files back to your phone through the control host.

Telegram-style dark topic showing slash commands, worker status, a Codex working state, and a final disk pressure summary.
Simulated product view Telegram topic control for a private Brainstack context.

Telegram-style interface with an ops-worker topic. The operator checks workers and runs a disk-pressure check on build-ubuntu. Brainstack replies with worker health, Codex working state, and a final disk-pressure summary.

From Telegram

/newctx ops-worker control host Create or bind a reusable topic to a machine context.
/workers Check worker reachability, outbox state, and harness readiness.
/run check the deploy logs Send one job into the stored harness session for that topic.
/crons List scheduled reminders or proactive Codex jobs owned by telemux.

From an enrolled machine

brainctl telegram send-file --config ~/.config/brainstack/brainstack.yaml --file ~/Downloads/report.pdf Stream a local file over SSH to telemux so Telegram receives it without client-side bot secrets.

Features

The parts operators usually end up building by hand

⌕

Local search over the shared brain

Search uses derived local indexes, while markdown and artifacts remain reviewable in git.

⇵

Agent-friendly save path

Agents can save transcripts, notes, artifacts, and draft changes without pushing directly to the shared-brain repo.

▣

Machine-to-Telegram file relay

Send yourself a PDF, log, image, or build artifact from an enrolled machine; the file streams through the control host's telemux path.

⚙

Deterministic runtime rendering

Generated runtime env files are separate from operator-owned secrets env files, and services run without ambient repo env files.

💻

Agent-ready runbooks

Codex gets installable Brainstack skills, while Claude and Cursor get concrete shared-brain guidance from checked-in templates.

✓

Doctor-first operations

Health checks report Bun, Git, SSH, Tailscale, harness paths, worker trust, services, and queued work.

Brainstack architecture diagram showing agent tools, brainctl, braind, the shared-brain git repository, Telegram control, and private workers.
Simulated architecture view Private shared-brain architecture with optional Telegram control and tailnet workers.

Architecture diagram with agent tools on the left, brainctl and braind in the middle, the shared-brain git repository as the memory source, optional Telegram control, and private workers on the tailnet.

FAQ

Common questions

No. Brainstack gives those harnesses shared context, a write path, worker routing, and operational checks. The harness still does the reasoning and code work.
In a separate shared-brain git repo. Brainstack keeps product code and your memory data separate, then builds fast local search over that repo.
Ordinary Mac clients can use a compiled brainctl binary with client bootstrap assets and public skills embedded, so they do not need Bun or a Brainstack source checkout. Control hosts and source-run workers still need Bun because they run Brainstack services from source.
The packaged skills are generic product runbooks: shared-brain usage, client discipline, operator checks, curation, worker ops, and file relay. Exact hostnames, Telegram routing, local paths, and personal topology belong in a private overlay skill.
No. The core shared-brain service and brainctl CLI work without telemux. Telegram is for operators who want phone-friendly control topics and scheduled routines.
Yes, when telemux is enabled and the invite includes the control-host SSH config. brainctl telegram send-file streams the file over SSH to the control host and lets telemux deliver it. The command rejects symlinks, oversized files, and sensitive-looking filenames unless you explicitly override the guard.
The default posture is private: loopback bind, trusted tailnet exposure, and operator-owned machines. Do not put it on the public internet unless you deliberately add the app-layer controls for that posture.

Get started

Bring one private machine and one shared-brain repo.

That is enough for the first pass: bring up one control host, connect the shared-brain repo, prove doctor is clean, then decide which Mac, Linux, Telegram, and worker surfaces are worth adding.

Talk about Brainstack Compare the suite