Skip to content
AIOS

Quickstart

Start with an individual workspace. It is useful on its own and does not require a Team Brain.

  1. Look for a toolkit that is already here

    Terminal window
    aios --version

    If that answers, do not install anything. Skip step 2, set AIOS_TOOLKIT_DIR in step 3, and inspect with the toolkit you already have — installing over an existing setup is the thing this sequence exists to avoid.

  2. Install the toolkit — only if step 1 came up empty

    Install only after the v2.1.0 Git tag and @aiosbrain/aios@2.1.0 npm version are published. A documentation preview does not mean the release is available.

    npm install --global @aiosbrain/aios@2.1.0

    With no toolkit on the machine there is nothing to inspect with, so this comes first by necessity. It only adds the aios command: nothing is cloned, scaffolded, updated, or connected, and no existing workspace is touched. Step 3 still inspects before anything mutates.

    Prefer a checkout you can read and pin exactly? Use the pinned public release instead — Individual workspace setup shows both paths side by side and explains which one to pick.

  3. Point AIOS_TOOLKIT_DIR at the toolkit

    The scaffold templates and validators live alongside the CLI, and later steps need their path — including when you skipped step 2 because aios was already installed.

    Terminal window
    # installed from npm (globally):
    export AIOS_TOOLKIT_DIR="$(npm root -g)/@aiosbrain/aios"
    

    # or, from a pinned release clone:
    export AIOS_TOOLKIT_DIR=/path/to/aios-workspace

    Check it resolved before moving on:

    Terminal window
    ls "$AIOS_TOOLKIT_DIR/validation/validate-all.sh"

  4. Inspect before changing anything

    Terminal window
    aios onboard --inspect --json

    Review the workspace candidates, Git cleanliness, toolkit state, and Brain configuration first. If a workspace already exists, repair that one rather than creating a second.

  5. Create or repair your individual workspace

    Follow Individual workspace setup. A fresh workspace uses the consultant, employee, or business-owner context. An existing workspace should be upgraded or repaired, not scaffolded over.

    During guided setup, AIOS may ask whether you are actively building a codebase with AI. This is a separate capability choice: Yes enables the optional GitHub Actions workflow that reports merge-time code health to the Team Brain; No is the default and does not add it. You can enable it later with aios update --with-ci-workflow.

  6. Validate it locally

    Terminal window
    "$AIOS_TOOLKIT_DIR/validation/validate-all.sh" /path/to/your-name-workspace

    AIOS_TOOLKIT_DIR is the toolkit location you exported in step 3.

  7. Choose whether you need shared memory

    You can stop after step 6. If a team already has a Brain, follow Join a Team Brain. If you are the team administrator, follow Team admin setup.

    After a successful Brain connection, toolkit 2.1 offers optional MCP setup for Claude Desktop, Claude Code, Codex and Cursor. Choose the hosts you want, or decline and run aios mcp install later from your connected workspace. Installing the toolkit itself does not change host configuration. Quit selected hosts before setup, then restart them and confirm the Brain tools appear. See Connect your agent.