Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Web Server

Use swarmie web to run the HTTP frontend (REST + SSE).

Primary sources:

  • CLI web command: crates/cli/src/cmd/server.rs
  • Server config and auth middleware: crates/server/src/lib.rs, crates/server/src/middleware.rs
  • Routes: crates/server/src/routes/mod.rs
  • Auth handlers: crates/server/src/routes/auth.rs

Start server

swarmie web
swarmie web --port 8080 --hostname 0.0.0.0
swarmie web --password "secret" --cors https://app.example.com --no-open

Password resolution:

  1. --password
  2. SWARMIE_SERVER_PASSWORD

If a password is provided, it is used as a first-run bootstrap password for local auth setup. Runtime auth uses session cookies and scoped API keys, not HTTP Basic auth.

Headless API mode

Use swarmie server when you need API and SSE endpoints without the embedded SPA or auto-open browser behavior.

swarmie server
swarmie server --port 8080 --hostname 0.0.0.0
swarmie server --password "secret" --cors https://app.example.com

Mode differences:

  • swarmie web: serve_spa=true, serves embedded web app and opens browser by default.
  • swarmie server: serve_spa=false, API-only surface (SPA paths return 404), no browser launch.

For external consumers (mobile apps, desktop clients, service-to-service integrations), prefer swarmie server and point clients to:

  • GET /health for liveness checks
  • GET/POST /sessions for session lifecycle
  • GET /sessions/{id}/events for session-scoped SSE
  • GET /events for global SSE

API surface

Core endpoints:

  • Health: GET /health
  • Sessions: GET/POST /sessions, GET/DELETE /sessions/{id}
  • Messaging: POST /sessions/{id}/messages, POST /sessions/{id}/abort
  • Session controls: mode/model/agent/objective/plan/undo/compact endpoints
  • Events: GET /events and GET /sessions/{id}/events (SSE)

CORS behavior

Default allowed origins include local dev hosts:

  • http://localhost:*
  • http://127.0.0.1:*

Use --cors <origin> repeatedly for additional origins.

Server config notes ([server])

TOML schema for [server] exists in crates/core/src/config/toml_types.rs (port, hostname, password, cors, permission_timeout_secs).

Current swarmie web runtime uses CLI/env wiring from crates/cli/src/cmd/server.rs; it does not currently read [server] values from resolved runtime config.