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. Inspect the machine

    Terminal window
    aios onboard --inspect --json

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

  2. Clone the source repository only when needed

    git clone --branch v0.10.0 --depth 1 https://github.com/aiosbrain/aios-workspace.git aios-workspace && test "$(git -C aios-workspace rev-parse HEAD)" = "5fded34256ad9e7eea4ad28ee50a8f24e1610dc8"
cd aios-workspace

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

  3. Choose one context and scaffold

    Terminal window
    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
    /path/to/aios-workspace/validation/validate-all.sh .

    Your workspace’s aios command is a shim that hands every command to the aios-workspace checkout, so it has to be able to find it. Cloning the source repository as aios-workspace alongside or one level above your workspace is enough. If you keep it somewhere else, point at it explicitly:

    Terminal window
    export AIOS_TOOLKIT_DIR=/path/to/aios-workspace

  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”