HTTP Gateway

The HTTP gateway exposes the same agent behind a REST/SSE API. Useful for integrating Minara into a web app, a Slack bot, or a custom front-end.

Start the server

minara serve
# listening on http://localhost:8080

Foreground by default. Ctrl+C stops the server. Flags:

• -p, --port <N> — override the listen port (also picks up GATEWAY_PORT).
• --auth-token <T> — bearer token required on every /v1/* request. Also reads GATEWAY_AUTH_TOKEN. Empty disables auth (dev only).

Environment variables:

• GATEWAY_PORT (default 8080)
• GATEWAY_AUTH_TOKEN — if set, every request must send Authorization: Bearer <token>. Empty disables auth (dev only).

One-command launch with the Web UI

minara serve --ui brings up the HTTP gateway and the Web UI in the same shell, as parallel processes. The gateway stays on 8080; the Web UI runs on 4173 (Vite preview build of apps/web-ui/dist).

minara serve --ui
# [gateway] listening on http://localhost:8080
# [ui]      preview ready at http://localhost:4173/

Cold-boot path: if apps/web-ui/dist/ is missing or older than apps/web-ui/apps/agent/src/, Minara auto-builds it before spawning the preview server. A file lock under apps/web-ui/dist/.build.lock prevents two concurrent serve --ui calls from racing the build.

Variants:

• --ui-dev runs vite (hot reload, port 5173) instead of preview. Use this when you're iterating on Web UI code.
• --ui-port <N> overrides the UI port.
• --no-build skips the auto-build check; assumes apps/web-ui/dist/ is already fresh. Fails fast (non-zero exit, clear error) if it is not.
• --daemon works the same as the bare serve --daemon: both the gateway and the UI subprocess are tracked in pidfiles (server.pid + web-ui.pid). --stop drains both ends with a PID-recycling guard so a stale UI pidfile pointing at an unrelated process is removed without signaling it.

See minara serve subcommand reference for the full flag table and daemon mechanics.

Run as a daemon

--daemon (or -d) detaches the server from your terminal, writes a PID file, and redirects stdout/stderr to a log file. Useful for leaving the gateway running across a reboot without setting up systemd.

minara serve --daemon              # start in the background
minara serve --status              # running? which PID?
minara serve --stop                # graceful SIGTERM, waits up to 10s

Defaults (override with --pid-file / --log-file):

• PID file: $MINARA_DATA_DIR/server.pid (typically ~/.minara/server.pid)
• Log file: $MINARA_DATA_DIR/logs/server.log

Exit codes follow the LSB init-script convention — --status returns 3 when the daemon is not running, so you can chain:

minara serve --status || minara serve --daemon

For production-grade supervision (restart-on-crash, journal integration, boot-time start) wire minara serve into systemd or your preferred supervisor instead. See Deployment for a sample unit file.

Health check

curl http://localhost:8080/healthz
# {"ok":true}

Chat

curl -X POST http://localhost:8080/v1/chat \
  -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "buy $50 of SOL"}'

For the streaming variant (Server-Sent Events), use /v1/chat/stream and read the response as a text stream.

See the full HTTP API Reference for every route, payload shape, and auth flow.