Self-Hosted Setup

Self-Hosted Setup

This guide covers everything beyond the basic quickstart: environment configuration, data persistence, reverse proxy with SSL, and keeping Engram up to date.

Environment Variables

All configuration is done via environment variables in your .env file.

Required

Variable	Description
OPENAI_API_KEY	Your OpenAI API key (or equivalent for other providers)

Memory (memcp)

Variable	Default	Description
MEMCP_DATA_DIR	/data/memcp	Directory where memcp stores its SQLite database and vector index
MEMCP_LOG_LEVEL	info	Log verbosity: debug, info, warn, error
MEMCP_MAX_MEMORIES	100000	Maximum number of memory entries per agent

Agent Runtime (openclaw)

Variable	Default	Description
OPENCLAW_PORT	3000	Port the runtime listens on
OPENCLAW_LOG_LEVEL	info	Log verbosity
DEFAULT_MODEL	gpt-4o	Default model for agents without explicit config

Dashboard (claw-control)

Variable	Default	Description
CLAWCONTROL_PORT	8080	Port the dashboard listens on
CLAWCONTROL_SECRET	(required in prod)	Session secret for dashboard auth. Set to a long random string.
OPENCLAW_API_URL	http://openclaw:3000	Internal URL to reach the openclaw service
MEMCP_API_URL	http://memcp:4000	Internal URL to reach the memcp service

Volume Persistence

Without volume mounts, all memory data is lost when containers restart. Mount the memcp data directory to a named volume or host path:

docker-compose.override.yml

services:
  memcp:
    volumes:
      - memcp-data:/data/memcp

volumes:
  memcp-data:

Or mount to a specific host path:

services:
  memcp:
    volumes:
      - /opt/engram/memcp:/data/memcp

Ensure the host path is readable/writable by the container user (UID 1000 by default).

Port Mapping

By default the compose file exposes these ports to localhost only. To expose to a specific interface:

services:
  claw-control:
    ports:
      - "0.0.0.0:8080:8080"  # all interfaces
      - "127.0.0.1:8080:8080"  # localhost only (default)

For production, expose only to localhost and use a reverse proxy.

Reverse Proxy with SSL (nginx)

The recommended setup is nginx in front of claw-control (and optionally openclaw).

Install certbot, get a certificate, then configure nginx:

server {
    listen 80;
    server_name dashboard.yourdomain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name dashboard.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Reload nginx: sudo nginx -s reload

Upgrade Procedure

To upgrade to the latest version:

# Pull new images
docker compose pull

# Restart with new images (zero-downtime is not guaranteed)
docker compose up -d

To pin to a specific version, set image tags in your compose file:

services:
  openclaw:
    image: ghcr.io/EngramTools/openclaw:v1.2.0
  memcp:
    image: ghcr.io/EngramTools/memcp:v1.2.0
  claw-control:
    image: ghcr.io/EngramTools/claw-control:v1.2.0

Backup

Back up the memcp data directory on a schedule. Example cron:

# Daily backup at 2am
0 2 * * * tar -czf /backups/memcp-$(date +%Y%m%d).tar.gz /opt/engram/memcp

The SQLite database in that directory contains all agent memories. The vector index is rebuilt from it on restart.