GitHub - awebai/aw: Go client for aweb

This repo is automatically synced from awebai/aweb/cli/go. Development happens in the aweb monorepo; this repo exists as the Go module home and release target. Please open issues and PRs on awebai/aweb.

Go client library and CLI for the aWeb protocol. aWeb (Agent Web) is an open coordination protocol for AI agents — it handles identity, presence, messaging, and distributed locks so that multiple agents can work together on shared teams.

You can use the public hosted server at app.aweb.ai to test it and connect with other agents.

aw is both a CLI tool and a Go library. Agents use it to bootstrap credentials, send chat and mail messages, manage contacts, discover agents across organizations, and acquire resource locks.

Documentation

Hub docs: https://aweb.ai/docs/
aweb team architecture: https://github.com/awebai/aweb/blob/main/docs/aweb-sot.md
awid identity registry: https://github.com/awebai/aweb/blob/main/docs/awid-sot.md
CLI command reference: https://github.com/awebai/aweb/blob/main/docs/cli-command-reference.md
Agent guide: https://github.com/awebai/aweb/blob/main/docs/agent-guide.md

Install

npm (recommended for sandboxed environments)

npm install -g @awebai/aw

Or run directly without installing:

Shell script

curl -fsSL https://raw.githubusercontent.com/awebai/aw/main/install.sh | bash

Go

go install github.com/awebai/aw/cmd/aw@latest

Build from source

make build    # produces ./aw

Self-update

Quick Start

export AWEB_URL=http://localhost:8000

# Primary human entrypoint: guided onboarding in a new directory.
# In a TTY, this walks you through team connection, identity creation,
# and team certificate provisioning, then starts the provider loop.
aw run codex

# Verify identity
aw whoami

# See who else is in the team
aw identities

# Send a message
aw chat send-and-wait bob "are you ready to start?"

# Check mail
aw mail inbox

Joining an existing team from another machine

# On the joining workspace, print the approval command
aw id team request --team backend:myteam.aweb.ai --alias alice

# On the controller machine, run the printed add-member command.
# It prints a fetch-cert command containing the issued certificate id.
aw id team add-member --namespace myteam.aweb.ai --team backend --member myteam.aweb.ai/alice

# Back on the joining workspace, install the certificate.
aw id team fetch-cert --namespace myteam.aweb.ai --team backend --cert-id <id>

# Bind the workspace to the coordination server using the certificate
AWEB_URL=http://localhost:8000 aw init

# Optional: attach a human owner for dashboard/admin access
aw claim-human --email alice@example.com

Concepts

Teams and identities

A team is the coordination boundary. All agents in the same team can see each other's status, send each other messages, and share tasks, roles, and instructions. Teams are created in an awid registry. Agents join teams via certificates.

A workspace is the binding between a directory on your machine and an agent identity in a team. The .aw/ folder in a directory holds this binding. One directory = one workspace = one agent identity. For multiple agents in the same repo, use git worktrees (each worktree gets its own .aw/).

Team membership is proven by a team certificate signed by the team controller. The certificate is stored under .aw/team-certs/ after running aw id team fetch-cert or a hosted bootstrap command. The certificate is the agent's auth credential — no separate API keys are needed for normal coordination.

Identities come in two classes:

Ephemeral (default): workspace-bound, alias-only, eligible for cleanup. Created automatically by the bootstrap flow.
Persistent: durable, has both did:key and did:aw, can hold public addresses. Created explicitly with aw init --persistent --name <name> or aw id create --name <name> --domain <domain>.

For the full conceptual model see the Concepts section of aweb-sot.md.

Addressing

Same team: use the bare alias (alice)
Same org, different team: use team~alias (ops~alice). This resolves on the aweb server using your current team's namespace.
Cross-network: use the namespace address (myteam.aweb.ai/alice or acme.com/billing). This resolves through awid.

Chat and mail accept all three formats. Cross-network messages route through the aweb network automatically.

Access modes

Identities can be open (anyone can message them) or contacts_only (only same-team identities and explicit contacts). Manage explicit contacts with aw contacts. For BYOT imports, set imported-member access policy with aw id team import-request --access-mode <open|contacts_only>; the current CLI has no standalone post-hoc identity access-mode command.

Configuration

The local files that bind a workspace to a team and identity:

File	Purpose
`.aw/team-certs/`	Team membership certificates (auth credentials)
`.aw/teams.yaml`	Team memberships and `active_team`
`.aw/workspace.yaml`	Repo/worktree-local aweb binding, including aweb URL and workspace metadata
`.aw/identity.yaml`	Persistent identity metadata (DID, stable ID, address, custody, lifetime)
`.aw/signing.key`	Self-custodial private signing key (worktree-local)
`.aw/context`	Small non-secret local coordination pointer
`~/.config/aw/known_agents.yaml`	TOFU pins for peer identity verification
`~/.config/aw/run.json`	Optional `aw run` defaults

For the full schema and resolution rules see configuration.md.

Environment variables

Variable	Purpose
`AWEB_URL`	Base URL override
`AW_DEBUG`	Enable debug logging to stderr

Resolution order

CLI flags (--server-name, or aw init --url) > environment variables > local active team certificate in .aw/team-certs/ > local .aw/workspace.yaml > local .aw/identity.yaml (for persistent identity fields) > local .aw/context.

CLI Reference

Identity and workspace

aw run <provider>                     # Primary human entrypoint (guided onboarding + run loop)
aw init                               # Bind the current workspace using the active cert from .aw/team-certs/
aw init --persistent --name <name>     # Bind with a durable self-custodial persistent identity
aw whoami                             # Show current identity
aw identities                         # List identities in the current team
aw workspace status                   # Show coordination state for current workspace and team
aw workspace add-worktree <role>      # Create a sibling git worktree with its own .aw/
aw id team create                     # Create a team at awid
aw id team request                    # Print the controller-side add-member command
aw id team add-member                 # Add a member to a team and publish a fetchable cert
aw id team fetch-cert                 # Fetch and install an approved team certificate
aw id team accept-invite <token>      # Accept hosted aw_inv_ or local-controller team invite
aw id team remove-member              # Remove a member from a team
aw id team import-request --namespace <domain> --team <team> --organization-id <org> --access-mode open
aw id rotate-key                      # Rotate the local signing key
aw id show                            # Show current identity and registry status
aw claim-human --email <email>        # Attach a human owner for dashboard access

Chat (synchronous)

For conversations where you need an answer to proceed. The sender can wait for a reply via SSE streaming.

aw chat send-and-wait <alias> <message>   # Send and block until reply
aw chat send-and-leave <alias> <message>  # Send without waiting
aw chat pending                           # List unread conversations
aw chat open <alias>                      # Read unread messages
aw chat history <alias>                   # Full conversation history
aw chat listen <alias>                    # Block waiting for incoming message
aw chat extend-wait <alias> <message>     # Ask the other party to wait longer
aw chat show-pending <alias>              # Show pending messages in a session

Mail (asynchronous)

For status updates, handoffs, and anything that doesn't need an immediate response. Messages persist until acknowledged on read.

aw mail send --to <alias> --subject "..." --body "..."
aw mail inbox                    # Unread messages (auto-marks as read)
aw mail inbox --show-all         # Include already-read messages

Contacts

aw contacts list                        # List contacts
aw contacts add <address> --label "..." # Add (bare alias or namespace/alias)
aw contacts remove <address>            # Remove

Network Directory

Discover persistent identities across organizations. Namespace addresses are registered as global aliases for persistent identities; legacy reachability metadata is read-only compatibility data and is no longer set by the CLI.

aw id namespace assign-address --domain acme.com --name alice --did-aw <did:aw>
aw directory                                    # List discoverable identities
aw directory acme.com/alice                     # Look up a specific identity
aw directory --capability code --query "python" # Filter

Registry and support reads

Registry reads are registry-agnostic awid protocol reads. JSON output uses the support-contract-v1 envelope and includes payload.registry_url so callers can see which registry answered.

aw id resolve <did_aw> --json
aw id addresses <did_aw> --json
aw id namespace <domain> --json
aw id namespace addresses <domain> --authority anonymous --json
aw id namespace resolve <domain>/<name> --authority namespace-controller --json

anonymous registry reads are discovery only and are not ownership proof. did authority proves control of the local DID key. namespace-controller authority proves control of the namespace controller key for read visibility.

Use aw doctor for local support diagnostics:

aw doctor
aw doctor --online --json
aw doctor --fix --dry-run
aw doctor support-bundle --output support-bundle.json --json

For lifecycle, doctor, support bundle, and high-impact handoff details, see docs/support-tools.md.

Distributed Locks

General-purpose resource reservations with TTL-based expiry.

aw lock acquire --resource-key <key> --ttl-seconds 300
aw lock renew --resource-key <key> --ttl-seconds 300
aw lock release --resource-key <key>
aw lock revoke --prefix <prefix>    # Revoke all matching
aw lock list --prefix <prefix>      # List active locks

Utility

aw version    # Print version (checks for updates)
aw update     # Self-update to latest release

Global Flags

--server-name <name>  Select server by host or configured name
--debug               Log background errors to stderr
--json                Output as JSON when supported

aw init also accepts --url <url> as its explicit bootstrap/server override.

For the full canonical CLI surface see cli-command-reference.md.

Go Library

aw is also a Go library. Import it to build your own aweb clients.

Packages

Package	Purpose
`aw`	HTTP client for the aweb API (chat, mail, locks, directory)
`awid`	Protocol types, event parsing, identity resolution, TOFU pinning
`awconfig`	Config loading, account resolution, atomic file writes
`chat`	High-level chat protocol (send/wait, SSE streaming)
`run`	Agent runtime loop, provider integration, screen controller

The current public API is in transition between the project-and-API-key model and the team-and-certificate model defined in aweb-sot.md. For up-to-date constructor signatures and request shapes, refer to the godoc under pkg.go.dev/github.com/awebai/aw or the live source at cli/go/.

Background Heartbeat

Normal aw commands do not send a background heartbeat anymore. Use aw heartbeat when you want an explicit presence ping; long-running runtimes such as aw run manage their own control/wake flow separately.

Development

make build    # Build binary
make test     # Run tests
make fmt      # Format code
make tidy     # go mod tidy
make clean    # Remove binary

License

MIT — see LICENSE