Service Management

Recollectium can run as a managed service for adapters and clients, or as a foreground process for development.

Service types

api: local HTTP JSON API with memory, workspace, embedding, health, version, and capability operations.
mcp: MCP HTTP server using SSE transport.
webui: local browser control plane for managing Core from a browser.

Only one managed service runs at a time.

Start

recollectium service start api
recollectium service start mcp
recollectium webui start

Example success output:

{"endpoint":"http://127.0.0.1:8765","pid":12345,"status":"started","type":"api"}

WebUI status uses the configured browser endpoint, usually http://127.0.0.1:8766.

Status

recollectium service status

Running:

{"endpoint":"http://127.0.0.1:8765","pid":12345,"running":true,"type":"api"}

Not running:

{"running":false}

Discovery

recollectium service discover --json

Adapters should use discovery instead of hardcoding PID files, runtime paths, host, port, or service type.

When a managed service is running, service discover --json returns compact JSON with a status field and a compact service summary. When no service is running, compact output can be as small as { "status": "not_running" }. Use --verbose when you need full paths, version metadata, or stale details.

Stop

recollectium service stop

Recollectium sends SIGTERM and waits for graceful exit. If needed, it falls back to SIGKILL.

Restart

recollectium service restart
recollectium service restart --type api
recollectium service restart --type mcp
recollectium webui restart

Use --type when no running service or stale PID metadata can identify the previous type.

Foreground dev serve mode

recollectium dev serve --host 127.0.0.1 --port 8765

dev serve is useful for development and debugging. It blocks until interrupted.

Foreground WebUI serve mode

recollectium webui serve --host 127.0.0.1 --port 8766

webui serve is the foreground browser control plane for local development. It blocks until interrupted and should stay bound to localhost unless private-network controls protect the endpoint.

Runtime files

The service manager writes runtime metadata under the configured runtime directory. It includes a PID file and service-discovery.json.

Service stdout and stderr go to service logs in the logs directory. See Logs.

Security reminder

The v1 API, MCP, and WebUI services are unauthenticated. Keep them bound to localhost unless private networking and access controls protect the endpoint.