reflexio services

The default open-source setup runs:

• A FastAPI backend on port 8081, using local SQLite for storage and no authentication.
• A Next.js docs site on port 8082 (when running from a source checkout; silently skipped for PyPI installs).
• An optional embedding daemon on port 8072 when REFLEXIO_EMBEDDING_PROVIDER=local_service or CLAUDE_SMART_USE_LOCAL_EMBEDDING=1.

Command: reflexio services start

Starts the backend and docs servers as subprocesses and blocks until you interrupt with Ctrl-C.

reflexio services start [OPTIONS]

Options

Behavior

1. Loads .env from the current directory, then from ~/.reflexio/.env. On the very first run, ~/.reflexio/.env is auto-created from the bundled template.
2. First-run check (backend launches only): when the selected services include backend and no LLM provider key is set in the environment (or the only keys set don't support text embeddings), an interactive wizard prompts for a provider and key before launching the backend. The wizard writes the chosen key to ~/.reflexio/.env. On a non-interactive stdin (CI, nohup, containers) the wizard is skipped and the command exits with a pointer to the .env file instead of launching uvicorn. Invocations that omit the backend — e.g. --only docs or --only frontend — skip the check entirely and will not prompt or error on a missing key.
3. Sets API_BACKEND_URL=http://localhost:{backend-port} so other tools know where the backend is listening.
4. When local embedding service mode is selected, launches reflexio embeddings serve before the backend and points the backend at REFLEXIO_EMBEDDING_SERVICE_URL.
5. Launches uvicorn reflexio.server.api:app for the backend, with auto-reload unless --no-reload is passed.
6. Launches the Next.js docs dev server from the repo's docs/ directory, if it exists. PyPI installs silently skip the docs service since the Next.js source is not shipped in the wheel.

No JWT secret or external database setup is required - the default run is a single-process SQLite-backed server. A backend launch requires one LLM provider API key; the first-run wizard collects it, or run reflexio setup init ahead of time to configure it yourself. Docs-only invocations don't need a key.

Examples

# Start backend + docs with defaults (8081 and 8082)
reflexio services start

# Only the backend, no auto-reload
reflexio services start --only backend --no-reload

# Local embedding daemon only
reflexio services start --only embedding

# Backend on a custom port
reflexio services start --backend-port 9000

Command: reflexio services stop

Stops running services by killing processes listening on the configured ports. Sends SIGTERM first, then escalates to SIGKILL after a grace period unless --force is set.

reflexio services stop [OPTIONS]

Options

Examples

# Graceful shutdown of backend + docs
reflexio services stop

# Force-kill everything immediately
reflexio services stop --force

# Stop only the docs service
reflexio services stop --only docs

Prerequisites

• Python ≥ 3.12 with the reflexio-ai package installed (or via uv run).
• Node.js + npm — only required when running the docs site from a source checkout.

See Local OSS Get Started for end-to-end setup.