Self-hosted AIOE
Ports and endpoints
The ports AIOE's services listen on, the addresses clients call, and the network paths a firewall must allow.
What each AIOE service listens on, which paths it serves, and which connections a firewall must allow. The full API reference is in API reference.
Listening ports
| Service | Port | Protocol | Notes |
|---|---|---|---|
| API | 3001 | HTTP | Set with PORT. Put TLS in front of it (ingress, load balancer or Container Apps). |
| Console | 8080 | HTTP | nginx serving the static console. |
| Mesh relay | 8080 | HTTP | aioe-relay --http. Public, behind TLS. |
| Overlay gateway | 8080 | HTTP | aioe-gateway --http. Private: only the API calls it. |
| Overlay gateway | 51820 | UDP | WireGuard (--listen-port). |
| Overlay agent on a node | any | UDP | WireGuard. --listen-port 0 reuses the last port, or picks a free one. |
| PostgreSQL | 5432 | TCP | In the reference layouts. |
| Redis | 6379 | TCP | In the local reference layout; Azure Managed Redis uses 10000 with TLS. |
Paths on the API
Every path is under the API's public address (PUBLIC_URL).
| Path | Who calls it | What it is |
|---|---|---|
/healthz | Probes | Liveness, with the running version. |
/readyz | Probes | Readiness. |
/.well-known/aioe.json | Workbenches, the console, the mobile app | The public discovery document. |
/.well-known/aioe-jwks.json | Workbenches, nodes | The platform's public signing keys. |
/relay/v1/device/code, /relay/v1/device/token, /relay/v1/token | Workbenches, nodes | Enrolment and token refresh. |
/relay/v1/workbench/stream, /relay/v1/workbench/respond, /relay/v1/workbench/events | Workbenches | The relay: the long-lived stream, answers and events. |
/relay/v1/devices/… | The console, the mobile app | Remote control of one workbench. |
/relay/v1/mesh/… | Overlay agents | The mesh relay, passed through to the relay service when AIOE_RELAY_UPSTREAM is set. |
/ingest/v1 | Workbenches, nodes | Events, usage, audit and task snapshots. |
/catalogue/v1 | Workbenches, nodes, the console | The published catalogue. |
/policy/v1 | Workbenches, nodes, the console | The policy that applies, with an ETag. |
/fleet/v1/… | Workbenches, nodes, the console | Registration, heartbeats and the fleet list. |
/mesh/v1/… | Overlay agents | The overlay's coordination service. |
/tools/v1/… | Workbenches, nodes | Tool servers machines start, and call counts. |
/secrets/v1/… | The console, workbenches, nodes | Secrets for agents' tools. |
/projects/v1/…, /portfolio/v1/…, /memory/v1/…, /notifications/v1/… | Everyone signed in, workbenches, nodes | Projects, the portfolio, memory and the inbox. |
/source/v1/… | The console, nodes, GitHub and Azure DevOps | Source-control connections, linked accounts and webhooks. |
/people/v1/…, /platform/v1/organisation | The console, workbenches | The signed-in person, and the organisation. |
/admin/v1/… | Administrators and operators | Administration: policy, catalogue, tools, roles, audit, nodes, budgets. |
Paths on the mesh relay
| Path | What it is |
|---|---|
/relay | WebSocket transport for WireGuard packets. |
/relay/stream, /relay/send | The same packets over plain HTTPS, for proxies that refuse WebSockets. |
/healthz | Health check. |
Firewall rules
| From | To | Port | Why |
|---|---|---|---|
| Workbenches, nodes, phones, browsers | API host | 443/TCP | Everything: enrolment, the relay stream, ingest, policy, catalogue. The only connection a workbench must make. |
| Browsers | Console host | 443/TCP | The console. |
| Browsers | Your identity provider (for Entra ID, login.microsoftonline.com) | 443/TCP | Sign-in. |
| Browsers | graph.microsoft.com | 443/TCP | The console's people pickers, when you use them. |
| API | Your identity provider | 443/TCP | Fetching signing keys to check tokens. |
| API | PostgreSQL, Redis | 5432, Redis port | Storage. |
| API | Overlay gateway | 8080/TCP | Remote control over the overlay. |
| API | Mesh relay | 443/TCP | Passing /relay/v1/mesh through, when AIOE_RELAY_UPSTREAM is set. |
| API | Your OTLP collector | the collector's port | Traces and metrics, when on. |
| Overlay agents | STUN servers (stun.cloudflare.com:3478, stun.l.google.com:19302 by default) | UDP | Finding a node's public address. Optional. |
| Overlay agents | Each other | UDP | Direct WireGuard paths. Optional: without them traffic goes through the mesh relay. |
| Overlay agents | Mesh relay | 443/TCP | Relayed WireGuard. |
No rule is needed into any workbench or node.
Limits
| Limit | Value |
|---|---|
| Request body | 4 MB (a workbench backup may be up to 16 MiB). |
| Rate limit | 600 requests a minute per client address, counted by each API replica. |
| Remote-control answer | AIOE_RPC_TIMEOUT, 30 s by default. |
| Enrolment code | AIOE_DEVICE_CODE_TTL, 600 s; a node's join request AIOE_NODE_CODE_TTL, 24 hours. |
| Polling for an enrolment | AIOE_DEVICE_POLL_INTERVAL, every 5 s at most. |
| Device access token | AIOE_ACCESS_TOKEN_TTL, 3600 s. |
| Device refresh token | AIOE_REFRESH_TOKEN_TTL, 30 days, replaced on every use. |
| A workbench shows offline after | AIOE_OFFLINE_AFTER, 90 s without a heartbeat. |