Install Brainstack

Start with the local proof if you are evaluating

If you are not ready to enroll a real machine yet, run the local proof first. It uses a disposable shared-brain shape under /tmp and does not require Telegram, a worker, or Tailscale exposure.

Choose the role first

Brainstack setup starts with the machine role:

• control: runs braind, optional telemux, and the shared-brain repo.
• client: reads the shared brain, refreshes skills, and writes imports/proposals.
• operator: a client with admin/operator affordances.
• worker: runs delegated jobs over normal OpenSSH on the tailnet.

If an AI harness is installing Brainstack for you, it should ask for the role before touching config.

Existing Brainstack: enroll a Mac client

The operator creates a private invite on the control host. Replace CONTROL_HOST with the private SSH name of your Brainstack control machine:

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

On the Mac client, install from the published release and provide the invite through an interactive prompt or a private file. Do not paste invite values into shared shell history.

curl -fsSL 'https://github.com/Caimeo-com/brainstack/releases/latest/download/install.sh' | sh
brainctl doctor --config ~/.config/brainstack/brainstack.yaml

For a non-interactive local file path:

chmod 600 ~/brainstack-invite.txt
curl -fsSL 'https://github.com/Caimeo-com/brainstack/releases/latest/download/install.sh' | sh -s -- \
  --invite-file ~/brainstack-invite.txt \
  --skills-profile client

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

The installer downloads brainctl. Enrollment, config rendering, token installation, skills, hooks, and doctor checks live in the versioned CLI.

New Brainstack: create a control host

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

Then inspect the generated config, run smoke tests, initialize, enable services, and run doctor:

bun run packages/brainctl/src/main.ts smoke \
  --profile single-node \
  --config ~/.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
brainctl doctor --config ~/.config/brainstack/brainstack.yaml

Good AI-assisted install prompt

Install Brainstack on this machine.
This machine is joining an existing Brainstack.
Ask me for the private invite when you need it.
Default to client unless I say operator.
Stop and tell me if Git, SSH, Tailscale, or the selected harness is missing.

The harness should not invent tokens, hostnames, SSH pins, or tailnet state.

Telegram as a control surface

When telemux is configured, Telegram is not a separate product to learn. It is a phone-friendly way to ask Brainstack for the same lifecycle work you could run from the CLI.

Examples:

install voice on erbine
install transcription on valkyrie
/updates
/curator_status
/curator_run
/proposals pending

Brainstack should translate supported natural requests and slash commands into the canonical brainctl operations, run them on the right machine, show progress for slow work, and report the result in the same Telegram topic.