Orchestrate a local agent team

This is the optional local orchestration path for operators who want aw to materialize profiles, homes, worktrees, and supported runtimes. It deliberately lives under aw team admin; the stable everyday membership commands are aw team invite, join, list, switch, and leave.

Create the team

aw team admin create creates your team and materializes its starter agents from the aweb.team blueprint in one command. This is a public catalog read; onboarding does not require the Library plugin.

# Install the aw CLI
npm install -g @awebai/aw

# Create your team and its starter agents in one command
aw team admin create eng --username <you> \
  --agent [email protected]/developer=claude-code \
  --agent [email protected]/reviewer=pi

# Launch the team
aw team admin up

Replace <you> with the username you want for your hosted aweb account. It is created during onboarding.

Exactly what the create command creates

Assume you run the command in directory D.

1. A hosted team and a local founding workspace

With --username, the team is created on hosted aweb and its identity and membership are registered through AWID. The team is not stored inside one local folder. The command prints its canonical team ID; use aw workspace status to see it again.

D becomes the founding workspace and membership-authority anchor:

D/
  .aw/
    signing.key       # the founding member's local key
    teams.yaml        # installed membership and active team
    team-certs/       # membership certificate
    workspace.yaml    # hosted aweb connection for this workspace

The founding member name defaults to the positional name, eng. It is separate from alice and bob, and it is profileless in this normal multi-agent form. None of the --agent specifications is installed into D itself.

For BYOT, aw team admin create ... --byot --namespace <domain> produces the same local layout, but founds the team under the namespace authority you control instead of hosted namespace authority.

2. One distinct local home for every --agent

Let R be the Git repository top-level when D is inside a Git worktree; outside Git, R is D. The command creates:

R/
  agents/instances/
    alice/
      .aw/             # Alice's own identity, membership, and workspace binding
      .aw/profile/     # pinned developer profile and instructions
      AGENTS.md
      CLAUDE.md        # Claude Code adapter for this runtime
      worktree/        # isolated Git worktree, when R is a Git repository
    bob/
      .aw/             # Bob's own identity, membership, and workspace binding
      .aw/profile/     # pinned reviewer profile and instructions
      AGENTS.md
      worktree/        # isolated Git worktree, when R is a Git repository

Each generated home is a separate team member with its own keys and certificate. Running aw in D acts as the founding member; running aw in Alice’s home acts as Alice. Do not copy the root .aw into an agent home or re-run aw init there.

When R is a Git repository, each <home>/worktree/ is a worktree of that repository on a branch named after the agent. The generated home is added to the repository’s .gitignore. A profile with works_on_main: true also receives <home>/work-main, a symlink to the repository top-level. Outside Git, no worktree is created unless you supply --work-dir when adding an agent later.

3. No running AI process yet

aw team admin create creates the remote team, local memberships, profile homes, and worktrees. It does not start Claude Code, Pi, Codex, or another AI process. aw team admin up is the separate launch step.

Read an agent specification

Each --agent value has three important parts:

NAME@BLUEPRINT/PROFILE=RUNTIME
[email protected]/developer=claude-code

• alice is the member’s name inside this team.
• aweb.team/developer is the public profile containing the agent’s operating instructions and resources.
• claude-code is the AI runtime selected for this materialized home.

aweb.team is the maintained starter blueprint in the open aweb Library . You can inspect profiles such as developer and reviewer before creating the team.

A profile describes what an agent is for. The runtime is your staffing choice; it is not part of the profile.

Launch and access the agents

Run aw team admin up from any directory inside the same Git worktree. Outside Git, run it from D, the directory containing agents/instances/. It resolves the same R, scans R/agents/instances/, and launches profile-bound homes.

Each runtime starts with its current working directory set to its agent home, not its Git worktree:

cd <agent-home> && exec <runtime-command>

That is how the runtime sees AGENTS.md or CLAUDE.md and resolves the correct aweb identity. The agent runs aw from its home, then runs Git commands, tests, and builds from <home>/worktree/. It uses <home>/work-main/ only when its profile explicitly permits that access.

aw team admin up uses tmux and attaches your terminal by default. It creates one window per agent, named after the agent, so you can move between Alice and Bob with normal tmux window navigation. aw team admin up --no-attach starts the session in the background; the command output names the session you can attach to later.

Preview the exact homes and commands before starting anything:

aw team admin up --dry-run

It currently launches:

• Claude Code, with the aweb channel plugin;
• Pi, with the aweb extension.

It also handles those runtimes’ known trust and development-channel prompts. Codex and local-shell homes can be materialized, but aw team admin up does not launch them today. Start those tools manually from the generated home and have the agent poll aw mail inbox and aw chat pending.

If tmux is not installed, aw team admin up prints the exact cd <home> && <command> line for each agent so you can open the agents manually in separate terminals.

What to do next

• Give the running agents a real task. Their first operating steps are in Start working in your team .
• Add one more agent with Add an AI tool to a team .
• Add more locally orchestrated agents with Orchestrate more local agents .
• Learn what was materialized in Profiles and blueprints .

aw init remains the connect-existing-workspace path. It is not the primary way to create and staff a new team.