Lettuce Docs Tags Graph

lettuce serve

#docs#cli#reference
~3 min read

lettuce serve

Starts the local MCP + REST server for one vault.

lettuce serve [vault] [--port N]

vault is an optional path (defaults to the current directory). The default Lettuce app launches the same server automatically when you open it, so this command is for when you’re not running the app:

Options

Flag Default Notes
[vault] (positional) current directory The vault folder to serve
--port N 51234 Listen port

That’s the whole flag set — serve is intentionally minimal. The server always binds to 127.0.0.1 (loopback only), always exposes both the MCP and REST endpoints, and there’s no daemon flag or rate-limit flag (the paid AI tools carry a fixed runaway-loop backstop — see Agent reference/08 Errors and rate limits). One server instance serves exactly one vault.

Endpoints

Path Auth Purpose
POST /mcp bearer token JSON-RPC MCP endpoint (tools/list, tools/call, …)
/api/v1/… bearer token REST mirror of the tools (see Agent reference/10 REST API)
GET /health none Liveness probe — returns the plain text ok

Examples

Serve the current directory:

lettuce serve

Serve a specific vault on a custom port:

lettuce serve ~/Notes --port 8080

Run headless in the background (there’s no --daemon flag — use your shell or a supervisor):

nohup lettuce serve ~/Notes > /tmp/lettuce.log 2>&1 &
# …or a launchd / systemd unit for a long-lived server

Because it binds to loopback only, expose it remotely by fronting it with a tunnel (cloudflared, tailscale serve) rather than a bind flag — see Agent reference/02 MCP transport.

Self-maintenance

A long-lived lettuce serve also runs the schedule poller every 60s, so any > [!ai] directives scheduled in .lettuce/schedules.yml fire even with no GUI open — the wiki maintains itself headlessly.

Output

On start it prints the bind URL. The API key is not printed by default — so it can’t leak into a redirected logfile — only a hint:

Lettuce serving /Users/you/Notes
  REST: http://127.0.0.1:51234/api/v1
  API key: ephemeral (not saved) — re-run with --show-key to print it
  schedules: polling every 60s (headless)

Pass --show-key to print the actual token (to stdout, so it stays out of the captured banner):

lettuce serve ~/Notes --show-key

If no key is configured it mints an ephemeral one for the session (shown only with --show-key, not persisted). Add durable, scoped keys with [[CLI cookbook/08 lettuce keys|lettuce keys add]].

Health check

curl http://127.0.0.1:51234/health
# ok

No auth required for /health; it returns the literal string ok while the server is reachable. Use it as a liveness probe in scripts or a supervisor.