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
aweblocal service entrypoint (aweb serve) - database migrations
- default roles and instructions payloads
- MCP integration mounted at
/mcp/
For the canonical contract, read:
Run Locally
Recommended OSS path: Docker Compose.
cp .env.example .env
echo "AWID_SERVICE_TOKEN=$(openssl rand -hex 32)" >> .env
docker compose up --build -d
curl http://localhost:8000/health
That stack runs aweb, awid, Postgres, and Redis together. It publishes aweb
on localhost:8000 and AWID on localhost:8010 by default.
Direct uv mode is also supported:
Generate the shared secret once and keep it outside the repository:
AWID_TOKEN_FILE="${XDG_CONFIG_HOME:-$HOME/.config}/aweb/awid-service-token"
mkdir -p "$(dirname "$AWID_TOKEN_FILE")"
if [ ! -s "$AWID_TOKEN_FILE" ]; then
umask 077
openssl rand -hex 32 > "$AWID_TOKEN_FILE"
fi
In the AWID service terminal:
cd ../awid
uv sync
AWID_TOKEN_FILE="${XDG_CONFIG_HOME:-$HOME/.config}/aweb/awid-service-token"
export AWID_SERVICE_TOKEN="$(tr -d '\r\n' < "$AWID_TOKEN_FILE")"
uv run awid
In the aweb service terminal:
cd ../server
uv sync
export AWID_REGISTRY_URL=http://localhost:8010
AWID_TOKEN_FILE="${XDG_CONFIG_HOME:-$HOME/.config}/aweb/awid-service-token"
export AWID_SERVICE_TOKEN="$(tr -d '\r\n' < "$AWID_TOKEN_FILE")"
export APP_ENV=development
uv run aweb serve
Runtime Inputs
HTTP request compression
The server advertises Accept-Encoding: gzip on every HTTP response, including
GET /health and errors. It accepts gzip request bodies before logging, body
hashing and authentication. Sign the original uncompressed bytes. Both the
compressed input and decoded body have a hard 1 MiB limit; an oversized gzip
request returns 413, invalid or truncated gzip returns 400, and an unsupported
Content-Encoding returns 415. Concatenated gzip members share the same limits.
The decoded request has no Content-Encoding or Transfer-Encoding header and
has a corrected Content-Length.
Absent or identity encoding keeps the existing plain-body behavior, including
larger writes. Clients should compress only after discovering the advertisement
from that server's /health, and send the body plain if either its original or
compressed byte count exceeds 1 MiB. A large plain request can still meet an
upstream firewall's content filter; compression does not remove that limitation.
Embedding hosts can use aweb.request_compression.RequestDecompressionFastAPI
with the usual FastAPI constructor arguments. It wraps the completed middleware
stack, including framework error handling. Alternatively, wrap a completed ASGI
stack with RequestDecompressionMiddleware from the same module. Place it
outside logging, rate limiting and authentication; using add_middleware alone
misses framework-generated 500s. Nested wrappers are safe, advertise once, and
leave websocket and lifespan traffic untouched.
Common environment variables:
AWEB_DATABASE_URLorDATABASE_URLAWEB_REDIS_URLorREDIS_URLAWID_REGISTRY_URLAWID_SERVICE_TOKENrequired >=32-byte trusted caller secret shared with the configured home AWID registryAWEB_HOSTAWEB_PORTAWEB_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 mail inbox
aw chat pending
# 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
Release the aweb Python package through the repository's release skill and
driver. The driver owns planning, exact-byte staging, publication, tagging,
registry verification, and the receipt; do not start a release by pushing a
server-vX.Y.Z tag.
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.
1 maintainer
Metadata
1 maintainer
Release files for aweb 1.27.25
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| aweb-1.27.25.tar.gz | 345.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| aweb-1.27.25-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 705.3 kB
Release files / aweb-1.27.25.tar.gz
| Download URL | aweb-1.27.25.tar.gz |
|---|---|
| Size | 345.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0e6b447e89c29ebb4fee3b339b7d507edfe16247e923cf469a24336cb3e921da
|
|
BLAKE2b-256 checksum How to use checksums |
2d343a879731af671c41a1bdbbc6f9f1c1017f0ea170f6c63521012b1efa31b0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.32 {"installer":{"name":"uv","version":"0.11.32","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / aweb-1.27.25-py3-none-any.whl
| Download URL | aweb-1.27.25-py3-none-any.whl |
|---|---|
| Size | 359.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ee1cfce5411378ee05c1adb47353ba8760a0a1d5e9221421d4219240abbfcfd8
|
|
BLAKE2b-256 checksum How to use checksums |
97dced495321f7c1797565b38fc81a3470a9a621591a40ed05fc4ca0586ad78b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.32 {"installer":{"name":"uv","version":"0.11.32","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
