Emend
Local OSS

services

Start and stop a local open-source Emend backend and docs site.

emend services

Info
Local OSS only. services start / services stop launch the Emend backend and docs site on your machine.

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 EMEND_EMBEDDING_PROVIDER=local_service or CLAUDE_SMART_USE_LOCAL_EMBEDDING=1.

Run services commands from the project root so log paths resolve correctly.

Command: emend services start

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

emend services start [OPTIONS]

Options

PropType
--backend-portint
--docs-portint
--embedding-portint
--onlystr
--no-reloadflag
--storagestr

Behavior

  • Loads .env from the current directory, then from ~/.emend/.env. On the very first run, ~/.emend/.env is auto-created from the bundled template.
  • 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 ~/.emend/.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.
  • Sets API_BACKEND_URL=http://localhost:{backend-port} so other tools know where the backend is listening.
  • When local embedding service mode is selected, launches emend embeddings serve before the backend and points the backend at EMEND_EMBEDDING_SERVICE_URL.
  • Launches uvicorn emend.server.api:app for the backend, with auto-reload unless --no-reload is passed.
  • 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.
Tip
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 emend 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)emend services start # Only the backend, no auto-reloademend services start --only backend --no-reload # Local embedding daemon onlyemend services start --only embedding # Backend on a custom portemend services start --backend-port 9000

Command: emend 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.

emend services stop [OPTIONS]

Options

PropType
--backend-portint
--docs-portint
--embedding-portint
--onlystr
--forceflag

Examples

# Graceful shutdown of backend + docsemend services stop # Force-kill everything immediatelyemend services stop --force # Stop only the docs serviceemend services stop --only docs

Prerequisites

  • Python ≥ 3.12 with the emend-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.

PrevioussetupNext embeddings