Skip to content
AIOS

Individual workspace setup

An AIOS workspace belongs to one person. It holds that person’s context, work, decisions, harnesses, and sync client. It works offline; connecting a Team Brain is a separate choice.

Set up the workspace

Section titled “Set up the workspace”

  1. Install the toolkit

    Nothing below works until the aios command exists on this machine. Check first:

    Terminal window
    aios --version

    If that answers, skip this step — go straight to the inspection in step 2 and repair what is already here rather than installing over it. Otherwise pick one of the two supported ways to get the command. Installing it does not clone, scaffold, or modify any workspace; step 2 still inspects before anything changes.

    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.

    git clone --branch v2.1.0 --depth 1 https://github.com/aiosbrain/aios-workspace.git aios-workspace && test "$(git -C aios-workspace rev-parse HEAD)" = "b92173e7b5f4d7d5da615fe77c5a9fbe39873dd7"
cd aios-workspace
npm install

    This pins the supported public release, v2.1.0. A plain clone checks out the moving main branch and is only for contributors testing pre-release code.

    npm install is not optional — several validators load dependencies from the checkout, and skipping it makes validate-all.sh fail on a workspace that is actually fine.

    Then record where the toolkit lives, so your workspace can find it later:

    Terminal window
    export AIOS_TOOLKIT_DIR="$PWD"

  2. Inspect the machine

    Terminal window
    aios onboard --inspect --json

    This is read-only. If it finds a usable workspace, repair or upgrade that workspace instead of creating a duplicate.

  3. Choose one context and scaffold

    Terminal window
    "$AIOS_TOOLKIT_DIR/scripts/scaffold-project.sh" \
      --context employee \
      --slug your-name-workspace \
      --stakeholder "Your Company" \
      --owner your-name \
      --team "you" \
      --org your-org \
      --output ~/Projects/your-name-workspace

    The --team scaffold argument seeds local context. It is not a Team Brain invitation or a membership list.

  4. Validate the new repository

    Use the same --output path you chose above:

    Terminal window
    cd ~/Projects/your-name-workspace
    "$AIOS_TOOLKIT_DIR/validation/validate-all.sh" .

    Your workspace also ships its own bin/aios shim, which hands every command to an aios-workspace checkout. It looks for that checkout next to or one level above your workspace, or at AIOS_TOOLKIT_DIR — it does not find a globally npm-installed toolkit. If you installed with npm install -g, either call the global aios on your PATH (which works from inside the workspace) or export the package path:

    Terminal window
    export AIOS_TOOLKIT_DIR="$(npm root -g)/@aiosbrain/aios"

  5. Try an offline workflow

    Open the workspace in your supported coding agent and run an installed skill such as weekly synthesis. No workspace file content is uploaded automatically. An eligible file is uploaded only when you explicitly run aios push.

    Online commands that use a configured Team Brain are separate network operations. For example, aios whoami, aios query, and aios analyze --push transmit the request data needed for those operations; use the offline workflow when you do not want to make a network request.

Existing workspace

Section titled “Existing workspace”

Do not re-scaffold over it. Keep the toolkit on an exact published release and preview the managed-file update first:

Terminal window
aios update --preview --from /path/to/aios-workspace
aios update --from /path/to/aios-workspace --no-pull

The updater does not turn a release-tag checkout into main. When a new stable release is announced, explicitly fetch and select that tag before applying it. Dirty, diverged, detached-without---no-pull, or otherwise unsafe toolkit states are refused rather than overwritten.

Next decision

Section titled “Next decision”