Remote Deployment

This guide covers the production self-hosted path for Hoard using Docker + Caddy TLS.

Prerequisites

• A host with Docker and Docker Compose
• A DNS record pointing to your host
• Open ports 80 and 443

Recommended Path (Docker + Caddy TLS)

1. Clone Hoard on the server

   git clone https://github.com/thrr87/hoard.git
   cd hoard

2. Prepare deploy environment

   cp deploy/.env.example deploy/.env

   Edit deploy/.env:

   • HOARD_DOMAIN=your-domain
   • HOARD_SERVER_SECRET=long-random-secret

3. Start services

   docker compose -f deploy/docker-compose.yml --env-file deploy/.env up -d --build

4. Verify health

   curl -s https://your-domain/health

   Expect JSON with "status": "ok", "db_ready": true, and "migrations_pending": false.

5. Create client token(s)

   hoard tokens add codex-laptop --scopes search,get,memory,sync,ingest

Data Directory

In the Docker deployment, Hoard uses:

• HOARD_DATA_DIR=/data
• Persistent volume mounted at /data

This controls default locations for:

• config.yaml
• hoard.db
• server.key
• artifacts/
• daemon/log/sync lock files

Connect Clients to Remote Hoard

Recommended flow (manual token):

hoard setup remote --url https://your-domain --token hoard_sk_... --codex

Advanced automation flow (auto-provisions one token per client type):

hoard setup remote --url https://your-domain --admin-token YOUR_SERVER_SECRET --all

Caution

--admin-token is for automation workflows. For normal usage, prefer scoped tokens with --token.

Remote Bind Protection

Hoard defaults to loopback-only binding. Non-loopback bind requires explicit opt-in:

hoard serve --host 0.0.0.0 --allow-remote

Or in config:

server:
  allow_remote: true

SSH Tunnel Alternative

If you do not want to expose Hoard publicly:

ssh -N -L 19850:127.0.0.1:19850 user@your-server

Then clients use http://127.0.0.1:19850/mcp.

Availability Behavior (v1)

Hoard clients use best-effort retries for transient network failures. There is no durable offline write queue in v1.