hoard serve

The hoard serve command starts the HTTP MCP server for AI tool connections.

Usage

hoard serve [options]

Options

Option	Description
--daemon	Run in background
--status	Check if daemon is running
--stop	Stop running daemon
--install-autostart	Enable autostart on login
--port <n>	Override port (default: 19850)
--host <addr>	Override bind address (default: 127.0.0.1)
--allow-remote	Allow non-loopback bind addresses
--no-migrate	Skip schema migrations on startup

Examples

Start Server (Foreground)

hoard serve

Output:

Starting Hoard server on http://127.0.0.1:19850/mcp

Press Ctrl+C to stop the server.

Start as Daemon

hoard serve --daemon

Runs in background, survives terminal close.

Check Status

hoard serve --status

Output (when running):

Hoard server running (PID 12345)

Output (when not running):

Hoard server is not running.

Stop Daemon

hoard serve --stop

Install Autostart

hoard serve --install-autostart

Configures Hoard to start automatically on login.

macOS: Creates ~/Library/LaunchAgents/com.hoard.server.plist

Linux: Creates ~/.config/systemd/user/hoard.service

Server Configuration

In ${HOARD_DATA_DIR:-~/.hoard}/config.yaml:

server:
  host: "127.0.0.1"    # Bind address
  port: 19850          # Port number
  allow_remote: false  # Require explicit opt-in for non-loopback binds

Caution

Binding to 0.0.0.0 now requires explicit opt-in. Use --allow-remote or set server.allow_remote: true.

Background Sync and Watcher

When running hoard serve (or hoard mcp serve), Hoard starts the background scheduler and optional file watcher based on your sync configuration.

Scheduled sync runs every interval_minutes, and the watcher batches changes using watcher_debounce_seconds.

If the watcher is enabled but watchdog is not installed, Hoard logs a warning and continues without file watching.

Endpoints

Endpoint	Description
POST /mcp	MCP JSON-RPC endpoint
GET /health	Unauthenticated liveness + DB/schema readiness
GET /sync_status	Get connector sync status
POST /<tool>	Direct tool invocation (e.g., /search)

Test Connection

curl -X POST http://127.0.0.1:19850/mcp   -H "Content-Type: application/json"   -H "Authorization: Bearer YOUR_TOKEN"   -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Authentication

All /mcp requests require Bearer token:

Authorization: Bearer hoard_sk_544e528b4b1ae6...

Tokens are configured in ${HOARD_DATA_DIR:-~/.hoard}/config.yaml:

security:
  tokens:
    - name: "claude-code"
      token: "hoard_sk_544e528b..."
      scopes: ["search", "get", "memory", "sync", "ingest"]

Tip

HOARD_SERVER_SECRET must be set before starting the server when write mode is enabled. Use HOARD_REGISTRATION_TOKEN to register agents for Orchestrator (Beta).

Runtime Paths

By default Hoard uses ~/.hoard. Set HOARD_DATA_DIR to move default runtime paths:

export HOARD_DATA_DIR=/var/lib/hoard

Logging

Server logs to stdout (foreground) or to ${HOARD_DATA_DIR:-~/.hoard}/hoard.log when running as daemon.

View logs:

tail -f "${HOARD_DATA_DIR:-$HOME/.hoard}/hoard.log"

Troubleshooting

Port Already in Use

Error: Address already in use (port 19850)

Solutions:

1. Check for running instance: hoard serve --status
2. Stop it: hoard serve --stop
3. Or use different port: hoard serve --port 19851

Connection Refused

AI tool can’t connect:

1. Ensure server is running: hoard serve --status
2. Check URL matches config
3. Test with curl (see Test Connection example above)

Daemon Won’t Start

Check logs for errors:

cat "${HOARD_DATA_DIR:-$HOME/.hoard}/hoard.log"

Common issues:

• Config file errors
• Port conflicts
• Permission issues

See Also

• hoard setup — Configure AI tools
• MCP Interface — Protocol details
• Security — Authentication details