---
source: packages/pond/src/main.rs
expression: sub.render_long_help().to_string()
---
Run the HTTP API server (or MCP over stdio with --transport stdio).
Serves the wire protocol over HTTP on --host:--port. Most agent setups want `pond mcp` instead; `serve` is for the HTTP transport and for supervised deployments.
Usage: pond serve [OPTIONS]
Options:
--transport <TRANSPORT>
Wire transport: the HTTP API, or MCP over stdio
[default: http]
[possible values: http, stdio]
--host <HOST>
Bind address for the HTTP transport
[env: POND_HOST]
[default: 127.0.0.1]
--port <PORT>
Bind port for the HTTP transport
[env: POND_PORT]
[default: 9797]
--socket <PATH>
Serve HTTP on a Unix socket at this path instead of --host:--port.
The socket is owner-only (0600), so no other local user can reach it, and a successful connect means the server is ready (the store opens before the bind). Put it in a directory only you can write: the mode is set by path, so a shared one lets another user swap it. A `<path>.lock` beside it keeps a second server off the path; once that lock is held, any socket already at the path is treated as a dead run's and replaced, any other file is refused, and a clean stop removes the socket. Excludes --host/--port; POND_HOST/POND_PORT in the environment are ignored.
--allowed-host <HOST>
Public Host value the MCP route also accepts, on top of localhost.
MCP over streamable HTTP validates the Host header against an allowlist (the spec's DNS-rebinding defence), and the default list is loopback only - so a server reached by any other name answers /mcp with 403 until that name is listed here. Repeat the flag, or set the env to a comma-separated list. The /v1/* routes are not gated this way.
[env: POND_ALLOWED_HOSTS]
--with-sync
Also run periodic sync in-process, reusing this server's store and embedding model (no separate `pond sync` child cold-loading a second ~500 MB model). Sync output goes to stderr/tracing; stdout stays reserved for the transport
--sync-every <SYNC_EVERY>
Minutes between in-process syncs (requires --with-sync)
[default: 5]
--bootstrap <ADAPTER>
On startup, when NO adapters are configured yet, discover and enable this one (an init-equivalent step for supervised deploys). Never touches an existing [adapters.*] config; if discovery finds nothing, serve still starts and logs the `pond init` fix
-h, --help
Print help (see a summary with '-h')
Global options:
--storage-path <URL>
Storage destination: a local path or remote URL.
Accepts a bare path, `~/path`, `file://`, `s3://bucket/prefix`, `s3+https://host/bucket/prefix`, `gs://`, `az://`, or the keyword `local` (the platform default local data dir). Default: `[storage].path` from config, then the platform data dir (`~/.local/share/pond`).
[env: POND_STORAGE_PATH]
--config-file <PATH>
Config file to read (default: `~/.config/pond/config.toml`)
[env: POND_CONFIG_FILE]
-v, --verbose...
Increase logging verbosity
-q, --quiet...
Decrease logging verbosity
Examples:
pond serve HTTP on 127.0.0.1:9797
pond serve --port 8080
pond serve --transport stdio same as `pond mcp`
pond serve --host 0.0.0.0 --allowed-host pond.example.com reached by name
pond serve --socket /run/user/1000/pond.sock owner-only Unix socket, ready once it accepts