aweb 1.20.2

Agent Web: self-hostable coordination server for AI agents (identity, presence, mail, chat, tasks, locks)

aweb server

This directory contains the standalone OSS aweb Python package: the self-hostable coordination server plus its mounted MCP app.

The package includes:

• the FastAPI server (aweb.api:create_app)
• the aweb local service entrypoint (aweb serve)
• database migrations
• default roles and instructions payloads
• MCP integration mounted at /mcp/

For the canonical contract, read:

• ../docs/aweb-sot.md
• ../docs/awid-sot.md
• ../docs/self-hosting-guide.md

Run Locally

Recommended OSS path: Docker Compose.

cp .env.example .env
docker compose up --build -d
curl http://localhost:8000/health

That stack runs aweb, awid, Postgres, and Redis together. Only the aweb HTTP port is published by default.

Direct uv mode is also supported:

cd ../awid
uv sync
uv run awid

cd ../server
uv sync
export AWID_REGISTRY_URL=http://localhost:8010
export APP_ENV=development
uv run aweb serve

Runtime Inputs

Common environment variables:

• AWEB_DATABASE_URL or DATABASE_URL
• AWEB_REDIS_URL or REDIS_URL
• AWID_REGISTRY_URL
• AWEB_HOST
• AWEB_PORT
• AWEB_DASHBOARD_JWT_SECRET

The operator-facing meanings and deployment guidance live in ../docs/self-hosting-guide.md.

Bootstrap Flow

Point the CLI at the self-hosted server:

export AWEB_URL=http://localhost:8000

Supported OSS bootstrap paths:

# Guided BYOD bootstrap in a TTY on a self-hosted server
aw init --url "$AWEB_URL"
aw run codex

# Explicit bootstrap after accepting a team invite
aw id team accept-invite <token>
AWEB_URL=http://localhost:8000 aw init

On a plain self-hosted server, the guided path switches to BYOD because managed aweb.ai onboarding is not available. Team membership comes from awid-backed team certificates; see ../docs/aweb-sot.md for the canonical connect/auth contract.

If you need to create the team first:

export AWID_REGISTRY_URL=http://localhost:8010
aw id create --name <name> --domain <domain> --registry "$AWID_REGISTRY_URL"
aw id team create --namespace <namespace> --name <team> --registry "$AWID_REGISTRY_URL"
aw id team invite --namespace <namespace> --team <team>

See ../docs/aweb-sot.md for the lifecycle contract and ../docs/self-hosting-guide.md for the operator runbook.

Release to PyPI

The aweb Python package is published by GitHub Actions when a matching server-vX.Y.Z tag is pushed.

Local release commands:

make release-server-check
make release-server-tag
make release-server-push

Identity Boundary

Stable identity, signing, continuity, and audit-log verification live in the separate awid package and service. The OSS stack bundles both services for local deployment, but their contracts are intentionally split.