Configuration reference

luplo has two configuration surfaces: a client-side one used by the CLI and MCP server, and a server-side one used only by the Remote-mode FastAPI app. They are deliberately separated — the server never imports the client module, so adding a field to one does not touch the other.

Client: .luplo file + env vars

Resolution order

Highest priority wins:

  1. CLI flag (--project, --actor, --db-url, …)

  2. Environment variable (LUPLO_*)

  3. .luplo file (walked up from the current working directory)

  4. Built-in defaults

.luplo file

TOML. Created by lp init, editable by hand:

[backend]
type      = "local"                            # or "remote"
db_url    = "postgresql://localhost/luplo"
server_url = "https://luplo.example.com"       # only for remote

[project]
id   = "myapp"
name = "MyApp"

[actor]
id    = "<uuid4>"
name  = "Ryan"
email = "ehanyul99@gmail.com"

[research]
ttl_days = 90                                   # expiry for research items

find_config_file() walks up from CWD, so any subdirectory of the project inherits the root .luplo.

Environment variables (client)

Variable

Replaces

Notes

LUPLO_DB_URL

.luplo/backend.db_url

Used in Local mode.

LUPLO_SERVER_URL

.luplo/backend.server_url

Used in Remote mode.

LUPLO_PROJECT

.luplo/project.id

Override the active project.

LUPLO_ACTOR_ID

.luplo/actor.id

Override the active actor.

Defaults

  • db_url: postgresql://localhost/luplo

  • backend_type: local

  • research_ttl_days: 90

Server: env + luplo-server.toml

The Remote server (FastAPI, started via uvicorn luplo.server.app:app) reads configuration via [pydantic-settings]. Priority:

  1. Environment variables (LUPLO_*)

  2. .env file in the working directory (auto-loaded by pydantic-settings)

  3. luplo-server.toml in the working directory

  4. Defaults

The server does not authenticate callers — it trusts the network layer in front of it. See Running the Remote server for the shape.

All server settings

Setting

Env variable

TOML key

Default

PostgreSQL URL

LUPLO_DB_URL

db_url

postgresql://localhost/luplo

Default attribution actor

LUPLO_DEFAULT_ACTOR_ID

default_actor_id

"" (no fallback — every write must carry X-Actor)

Start worker in lifespan

LUPLO_WORKER_ENABLED

worker_enabled

false

Public base URL

LUPLO_BASE_URL

base_url

http://127.0.0.1:8000

Attribution (X-Actor header)

Every write handler resolves the actor id in this order:

  1. X-Actor: <uuid> on the request.

  2. LUPLO_DEFAULT_ACTOR_ID if set.

  3. HTTP 400 otherwise.

Reads do not require it. The actor referenced by X-Actor must exist in the actors table; provision it with lp init or directly in SQL.