Join a Team Brain

This guide is for a person joining a Team Brain that someone else administers. You do not join another person’s workspace. You create or repair your own workspace, receive membership in the shared Brain, and connect the two.

1. Set up your own workspace

Complete Individual workspace setup first. The workspace remains useful even if the Brain connection is delayed or declined.

Note

If you already have a workspace, use aios onboard --inspect --json and aios update --preview. Do not create a second workspace just to join a Brain.

2. Accept the Team Brain invitation

A Team Brain admin creates or re-invites your member record. The admin can use the Brain dashboard or run this from an AIOS toolkit/workspace with an admin API key:

aios member invite you@example.com --name "Your Name" --handle you \
  --role member --tools all

The command issues either a magic-link email or a manual sign-in credential and best-effort cascades invitations to configured tools such as Linear, Slack, and GitHub. A tool invitation failure does not block Brain membership.

If the Brain has no mail provider configured, the magic-link email is accepted and then silently dropped — so expect your admin to hand you a password directly rather than waiting on an email that will not arrive.

The tool cascade is inert until an admin configures it

Linear, Slack, and GitHub each report skipped — quietly, with no error — until a Brain admin satisfies that tool’s prerequisite. Linear needs an enabled Linear integration with its API key stored under Admin → Integrations, not just the Member onboarding panel. Slack needs a workspace invite link in Admin → Integrations → Member onboarding, and only ever returns that link rather than sending an invite. GitHub needs an org in that panel. If you expected a Linear or Slack invite and nothing arrived, that is the first thing to check. See Member onboarding prerequisites.

Caution

This command invites you to the Team Brain and configured external tools. It does not grant access to the admin’s personal workspace repository.

3. Create your per-machine API key

After signing into the Brain dashboard, open My API keys and create a key. Dashboard sign-in and CLI authentication are separate. The key is shown once and has the form aios_<key_id>_<secret>.

Put it in the scaffolded workspace’s gitignored .env:

AIOS_API_KEY=aios_<key_id>_<secret>

4. Connect your workspace

1. Inspect, then run the guided Join path

   aios onboard --inspect --json
   aios onboard

   The wizard normalizes the candidate Brain URL, displays the canonical origin, and waits for your approval before saving it. The API key is authoritative for team identity; team_id is optional.

   It may also ask whether you are actively building a codebase with AI. Answering Yes opts this workspace into the optional GitHub Actions code-health workflow; answering No leaves that workflow out. This choice is separate from whether you are a consultant, employee, or business owner.

2. Validate identity

   aios whoami

   This calls GET /api/v1/me. Onboarding never runs aios push.

3. Preview the first share

   aios status
   aios push --dry-run

4. Push only after review

   aios push
   aios query "what decisions did we make this week?"

Only tier-eligible content on whitelisted paths can leave the machine. Untagged and admin content is blocked locally; the Brain independently rejects admin content.

5. Connect your agent (optional)

Toolkit 2.1 includes aios mcp install. After onboarding validates your Brain connection, it offers to configure Claude Desktop, Claude Code, Codex or Cursor. The offer defaults to No, and you choose which hosts to configure. Declining does not prevent you from using your workspace. Personal onboarding does not offer a Brain connection through MCP.

You can start the same setup later from your connected workspace:

aios mcp install
aios mcp status --json

Quit the selected hosts before installing; the installer refuses to change a running host and does not stop applications for you. Claude Code uses the current project’s .mcp.json; run setup from the project you want to configure. Codex and Cursor use global configuration. Claude Desktop is supported on macOS and Windows.

The installer verifies and pins @aiosbrain/mcp@0.2.1, and keeps your API key out of host configuration files. One owner-only credential file supplies one default Brain for all configured hosts. Other processes running as your user can read that credential. Existing malformed, edited or unowned entries are preserved and setup refuses to overwrite them.

Restart the hosts yourself and confirm the Brain tools appear. aios mcp status reports configuration and server-command verification; host loading remains unverified until you confirm it inside the application. Restart configured hosts again after changing credentials. Claude Code may also request project trust.

For an explicit preview or removal:

aios mcp install --host cursor --dry-run
aios mcp install --host cursor --uninstall

Uninstall removes only an unchanged installer-owned entry and retains the shared credential file. An MCP setup failure is reported without failing onboarding.

For administrators

See Team admin setup for Brain deployment, the admin account, and the member invitation sequence.