Ports & Services¶
Source: §02, §13 — Integrations, §14, §15 — Operations. Exact API shapes: API Reference.
Ports¶
| Component | Port | Default URL | Notes |
|---|---|---|---|
| Aetherium Engine | 5257 |
http://localhost:5257 |
Plain HTTP; reverse-proxy in prod |
| LM Studio (inference) | 1234 |
http://localhost:1234/v1 |
Engine chats at /v1; not auto-started |
llama.cpp llama-server (router-mode inference) |
8090 |
http://127.0.0.1:8090/v1 |
Optional slot backend (Backend: LlamaServer); presets in llama/models.ini, user-scope systemd unit installed by deploy.sh, pinned to its slot's card by an environment file from scripts/render-gpu-env.py |
llama.cpp llama-server, second router |
8091 |
http://127.0.0.1:8091/v1 |
llama-server-worker.service for a second local card's slot; presets in llama/models-worker.ini; installed by deploy.sh but not enabled by it |
| PostgreSQL | 5432 |
— | DB aetherium_refactor_db; PostgreSQL 15 |
| ChromaDB | 8000 |
http://localhost:8000 |
Published on 127.0.0.1 only; image pinned to chromadb/chroma:1.5.2 by digest; volume must be ext4/btrfs/xfs (POSIX locks) |
| ComfyUI (image gen) | 8188 |
http://localhost:8188 |
From ComfyUI_Endpoint setting |
ComfyUI, Z-Image Turbo (image_model: "z-image") |
8190 |
http://127.0.0.1:8190 |
comfyui-zimage.service, a user unit installed by deploy.sh and started and stopped by the arbiter; from ComfyUI_ZImageEndpoint setting |
ComfyUI, Wan 2.2 video (comfyui_video) |
8191 |
http://127.0.0.1:8191 |
comfyui-video.service, a user unit installed by deploy.sh and started and stopped by the arbiter; reads the model library read-only; from ComfyUI_VideoEndpoint setting |
| Qwen3-TTS voice services | 8100, 8101 |
http://127.0.0.1:8100/v1 |
qwen-tts.service speaks in a reference voice; qwen-tts-design.service turns a written voice description into a reference clip. User units installed by deploy.sh and never enabled: the arbiter starts and stops each for a run that declares it in gpu_services. URLs from Aetherium:Tts:BaseUrl and DesignBaseUrl |
| Ollama (alt inference) | 11434 |
http://localhost:11434/v1 |
Needs OLLAMA_ORIGINS=* |
| SearXNG (web search) | (unspecified) | from SearXNG_Url setting |
Compose: docker/docker-compose.searxng.yml; queried /search?q=…&format=json |
| Docs site (MkDocs) | 8765 |
http://127.0.0.1:8765 |
This documentation; pinned in mkdocs.yml |
The two llama-server routers, ComfyUI and the voice services bind AETHERIUM_LISTEN from their card-pin file: 127.0.0.1, unless their card is in another machine (Aetherium:Gpus:Cards:<card>:Host), where they bind the card's ListenAddress so the Engine can reach them. On that machine the optional scripts/net/aetherium-gpu-node-guard.nft (loaded by aetherium-gpu-node-guard.service, root to install) accepts 8090, 8091, 8100, 8101, 8188 and 8189 only from loopback and the Engine's machine, whose address is set in the file.
Project container host ports¶
Project containers get a host port from a pool the Engine scans, default 3000–3499. Each
workspace tier owns a sub-range, so a long-lived project keeps its number while short-lived ones
churn without pushing it around:
| Tier | Band | Why |
|---|---|---|
| Production | 3000–3099 |
Small and allocated bottom-up, so a kept project tends to keep its port across restarts |
| Staging | 3100–3199 |
Medium |
| Temp | 3200–3499 |
Large — this is where the churn is, and it is recycled hard |
Overridable per tier via Aetherium:Bridge:PortAllocation:Tiers:{Production|Staging|Temp}:{Start|End},
within the overall RangeStart / RangeEnd. Inspect the pool with
GET /api/openclaw/ports/pool, and release allocations whose container is gone with
POST /api/openclaw/ports/reconcile (System API).
Services & containers¶
| Service | Process / container | Notes |
|---|---|---|
| Engine | aetherium.service (systemd, Linux) |
Installed at /opt/aetherium; WorkingDirectory must be the install dir |
| PostgreSQL | aetherium-refactor-postgres (Compose) |
Health-checked via /api/health (CanConnectAsync) |
| ChromaDB | aetherium-chromadb |
Probed every 2 min; ulimit nofile: 65536; data at /var/lib/aetherium/chroma-data |
| SearXNG | separate compose file | Optional; started by start-aetherium-linux.sh |
Storage (Linux defaults): workspaces /var/lib/aetherium/workspaces, ChromaDB /var/lib/aetherium/chroma-data, fallback root /var/aetherium/…. On Windows: C:\aetherium\….
Health endpoints¶
| Endpoint | Checks | 503 when |
|---|---|---|
GET /api/health |
PostgreSQL only (CanConnectAsync) |
DB down |
GET /api/health/detailed |
DB, Docker, each LM Studio instance, scheduler queue, active builds, disk | only DB or Docker down — dead LM Studio / backed-up scheduler / filling disk still return 200 (parse the body) |
Warning
A green /api/health says nothing about inference, disk, or the scheduler. Read the /api/health/detailed body — it returns 200 even when those are broken.
Inbound orchestrator API (the surface integrations hit)¶
All unauthenticated. Full reference: API · Orchestration.
| Endpoint | Method | Notes |
|---|---|---|
/api/orchestrator/run |
POST | Synchronous; {projectId, message} + optional toolDefaults/samplingOverrides/handoffChecks |
/api/orchestrator/run-from-template |
POST | Atomic create + scaffold + build; synchronous |
/api/orchestrator/run-research |
POST | Returns immediately with projectId; poll for progress |
/api/orchestrator/runs/{projectId}/{runGuid} |
GET | Run status + container/port detail |
/api/orchestrator/runs/{projectId}/logs |
GET | Per-step build log |
/api/orchestrator/runs/{projectId}/cancel |
POST | Stop an in-flight run |
/api/tools/mcp-schemas?servers=<group> |
GET | Live MCP tool catalog |
/api/template · /api/template/reload |
GET · POST | List / reload templates |
Long builds vs. proxies
run and run-from-template are synchronous and hold the connection for the whole build. Raise the reverse-proxy read timeout (default 30–60 s) to the longest expected build, or you'll get a 502/504 while the Engine keeps working.
LM Studio APIs¶
- OpenAI-compatible:
POST /v1/chat/completions,GET /v1/models. - Native management:
GET /api/v0/models(reportsloaded/not-loaded),POST /models/load,POST /models/unload.
Webhook events¶
Glob-matched (e.g. build.*): build.started, build.step_completed, build.completed, build.failed, build.cancelled. Operator notices, each with a top-level message: finishing.awaiting_answer, finishing.failed, finishing.done, tool.approval.requested. Delivery headers: X-Aetherium-Signature: sha256=<hex> (HMAC-SHA256), X-Aetherium-Event, X-Aetherium-Delivery. Retry 3× (2/4/8 s) → dead-letter queue (in-memory, cleared on restart). Manage via /api/webhook.