Skip to content

lerim serve

Start the HTTP API server and daemon loop in a single process. The web UI is Lerim Cloud (separate repo), not bundled here.

Overview

lerim serve is the all-in-one runtime process. It starts:

  1. HTTP API — JSON endpoints used by CLI commands (ask, sync, maintain, status)
  2. Daemon loop — Background sync and maintain cycles on configured intervals

GET / may return a minimal HTML stub linking to Lerim Cloud when no bundled static assets are present.

This is the Docker container entrypoint (lerim up runs lerim serve inside the container), but it can also be run directly for development without Docker.

Info

For Docker-based usage, prefer lerim up which handles container lifecycle, volume mounts, and config generation automatically. Use lerim serve directly when developing or running without Docker.

Syntax

lerim serve [--host HOST] [--port PORT]

Parameters

--host string default: 0.0.0.0

Network interface to bind to. Use 0.0.0.0 to listen on all interfaces (required for Docker), or 127.0.0.1 for local-only access.

--port integer default: 8765

TCP port for the JSON API (and stub HTML at / when no bundled UI).

Examples

Start with defaults

lerim serve

Logs show the API bind address and daemon intervals (exact wording may vary by version).

Custom bind address

# Local-only access on a custom port
lerim serve --host 127.0.0.1 --port 9000

Development workflow

# Install in editable mode and run directly
uv pip install -e .
lerim serve

Tip

When running lerim serve directly (not via Docker), make sure your config exists at ~/.lerim/config.toml. Run lerim init first if needed.

What it starts

Component Description Endpoint
HTTP API JSON API for CLI and Cloud http://<host>:<port>/api/
Root Stub HTML or optional assets http://<host>:<port>/
Daemon loop Background sync/maintain on intervals — (internal)

The daemon loop uses sync_interval_minutes and maintain_interval_minutes from ~/.lerim/config.toml (defaults are in the shipped default.toml).

Exit codes

Code Meaning
0 Clean shutdown (SIGINT/SIGTERM)
1 Startup failure (port in use, config missing)