Self-Hosted Deployment

Run the smoltbot gateway on your own infrastructure with Docker or Kubernetes

Self-Hosted Deployment

Run the smoltbot gateway on your own infrastructure for full data residency control. All traces, integrity checkpoints, and agent data stay within your network. The self-hosted gateway is a Node.js adapter that runs the same code as the managed Cloudflare Workers service — identical behavior, your infrastructure.

Self-hosted deployment requires an Enterprise license. Contact us to obtain a license key. Enterprise includes hybrid analysis mode, SSO/SAML integration, and dedicated support.

Deployment options

	Managed (Cloud)	Docker Compose	Kubernetes (Helm)
Best for	Most teams	Small teams, eval, dev	Production at scale
Infrastructure	None (Mnemom hosts)	Single VM or server	K8s cluster
Setup time	Minutes	~10 minutes	~30 minutes
Scaling	Automatic	Manual	HPA auto-scaling
Data residency	Mnemom cloud	Your infrastructure	Your infrastructure
High availability	Built-in	Single node	Multi-replica, PDB
Monitoring	Dashboard	Prometheus + logs	Prometheus + ServiceMonitor

Prerequisites

• An Enterprise license JWT from mnemom.ai/dashboard
• An Anthropic API key (required for AIP integrity analysis)
• Optional: OpenAI and Gemini API keys for multi-provider tracing

AIP defaults to fail-open mode. If the analysis LLM is unreachable, integrity checks will silently pass. For production deployments handling sensitive operations, set failure_policy: { mode: "fail_closed" } in your AIP configuration.

---

Quick Start: Docker Compose

The fastest way to get a self-hosted gateway running. Includes PostgreSQL, Redis, and automatic database migrations.

Requirements

• Docker 24+ and Docker Compose v2+
• 2 GB RAM minimum, 4 GB recommended
• 10 GB disk space

1. Clone the repository

   git clone https://github.com/mnemom/smoltbot.git
   cd smoltbot/deploy/docker
   
2. Configure environment

   Copy the example environment file and fill in your credentials:

   cp .env.example .env
   

   Edit .env and set the required values:

   # Required
   POSTGRES_PASSWORD=<strong-password>
   SUPABASE_URL=http://postgres:5432
   SUPABASE_KEY=<your-supabase-service-role-key>
   MNEMOM_LICENSE_JWT=<your-enterprise-license-jwt>
   ANTHROPIC_API_KEY=<your-anthropic-api-key>
   
   # Optional: additional providers
   OPENAI_API_KEY=<your-openai-key>
   GEMINI_API_KEY=<your-gemini-key>
   
3. Start the stack

   docker compose up -d
   

   This starts five services in order:

   1. PostgreSQL — database with health check
   2. Redis — caching layer with persistence
   3. Migrate — applies database schema (runs once, then exits)
   4. Gateway — HTTP proxy on port 8787
   5. Observer — background scheduler for trace processing
4. Verify health

   Wait about 30 seconds, then check the gateway health:

   curl http://localhost:8787/health/ready
   

   Expected response

   {
     "status": "ready",
     "checks": {
       "redis": { "status": "ok" },
       "supabase": { "status": "ok" },
       "license": { "status": "valid" }
     }
   }
   
5. Connect an agent

   Point the smoltbot CLI at your self-hosted gateway:

   npm install -g smoltbot
   smoltbot init --gateway=http://localhost:8787
   

   Make a test request:

   curl http://localhost:8787/anthropic/v1/messages \
     -H "x-api-key: $ANTHROPIC_API_KEY" \
     -H "content-type: application/json" \
     -d '{
       "model": "claude-haiku-4-5-20251001",
       "max_tokens": 256,
       "messages": [{"role": "user", "content": "Hello"}]
     }'
   

   Verify the agent is connected:

   smoltbot status
   

---

Production: Kubernetes with Helm

For production deployments with auto-scaling, high availability, and monitoring.

Requirements

• Kubernetes 1.27+
• Helm 3.12+
• kubectl configured for your cluster

1. Add the Helm chart

   cd smoltbot/deploy/helm
   
2. Create a Kubernetes Secret

   Store sensitive credentials in a Secret:

   kubectl create secret generic smoltbot-secrets \
     --from-literal=SUPABASE_URL=<your-supabase-url> \
     --from-literal=SUPABASE_KEY=<your-service-role-key> \
     --from-literal=ANTHROPIC_API_KEY=<your-anthropic-key> \
     --from-literal=MNEMOM_LICENSE_JWT=<your-license-jwt> \
     --from-literal=REDIS_URL=<your-redis-url> \
     --from-literal=DATABASE_URL=<your-postgres-url>
   
3. Install the chart

   helm install smoltbot ./mnemom-gateway \
     --set secrets.existingSecret=smoltbot-secrets \
     --set ingress.enabled=true \
     --set ingress.hosts[0].host=gateway.yourcompany.com \
     --set ingress.hosts[0].paths[0].path=/ \
     --set ingress.hosts[0].paths[0].pathType=Prefix
   
4. Verify the deployment

   kubectl get pods -l app.kubernetes.io/name=mnemom-gateway
   helm test smoltbot
   

What the chart deploys

• Gateway Deployment (2 replicas by default) — HTTP proxy with liveness, readiness, and startup probes
• Observer Deployment (1 replica) — background scheduler for trace processing
• Migration Job — Helm pre-install/pre-upgrade hook that applies database migrations
• Service — ClusterIP on port 8787
• NetworkPolicy — deny-all default with explicit allows for ingress, Redis, PostgreSQL, and upstream LLM APIs
• PodDisruptionBudget — ensures at least 1 replica during rolling updates
• Optional: Ingress with TLS, HPA, ServiceMonitor for Prometheus

Scaling

Enable the HorizontalPodAutoscaler for automatic scaling:

# values.yaml
hpa:
  enabled: true
  minReplicas: 2
  maxReplicas: 20
  targetCPU: 70
  targetMemory: 80

---

Architecture

In self-hosted mode, a Node.js adapter layer replaces Cloudflare-specific APIs while running the exact same gateway code:

Your App / Agents
  │
  ▼
Self-Hosted Gateway (Node.js, port 8787)
  │ ── KV adapter ──▶ Redis (or in-memory)
  │ ── fetch interceptor ──▶ Anthropic / OpenAI / Gemini (direct)
  │
  ├──▶ Observer (cron scheduler)
  │     ── builds AP-Traces
  │     ── runs AAP verification
  │     ── runs AIP integrity checks
  │
  ▼
PostgreSQL (Supabase or self-managed)
  │
  ├──▶ CLI (smoltbot status / logs)
  └──▶ Dashboard (mnemom.ai or self-hosted)

Adaptation layer — zero modifications to gateway source code:

Cloudflare API	Self-Hosted Replacement
KV Namespace	Redis (with in-memory fallback)
ctx.waitUntil()	Promise collection with drain after response
AI Gateway URL routing	Fetch interceptor rewriting to upstream APIs
ExecutionContext	Node.js shim with fire-and-forget semantics

---

Configuration Reference

Required

Variable	Description
SUPABASE_URL	Supabase project URL or PostgreSQL REST endpoint
SUPABASE_KEY	Supabase service-role key
MNEMOM_LICENSE_JWT	Enterprise license JWT from mnemom.ai/dashboard
ANTHROPIC_API_KEY	Anthropic API key (required for AIP analysis)

Optional: Providers

Variable	Default	Description
OPENAI_API_KEY	—	OpenAI API key for multi-provider routing
GEMINI_API_KEY	—	Google Gemini API key for multi-provider routing

Optional: Hybrid Analysis

Variable	Default	Description
MNEMOM_ANALYZE_URL	—	Delegate AIP analysis to Mnemom cloud (https://api.mnemom.ai/v1/analyze)
MNEMOM_API_KEY	—	Mnemom API key with analyze scope (required when MNEMOM_ANALYZE_URL is set)

In hybrid mode, only thinking/reasoning blocks are sent for analysis — raw prompts and responses never leave your infrastructure.

Optional: Infrastructure

Variable	Default	Description
REDIS_URL	—	Redis connection URL. Without Redis, an in-memory KV adapter is used (single-node only).
PORT	8787	HTTP listen port
HOST	0.0.0.0	HTTP bind address
SMOLTBOT_ROLE	all	gateway (HTTP only), scheduler (cron only), or all (both)
LOG_LEVEL	info	debug, info, warn, or error. Structured JSON to stdout.

---

Health Endpoints

Three Kubernetes-standard probes:

Endpoint	Purpose	Behavior
/health/live	Liveness probe	Always 200 unless deadlocked
/health/ready	Readiness probe	Checks Redis, PostgreSQL, and license validity
/health/startup	Startup probe	Returns 503 until initialization complete

Prometheus Metrics

The gateway exposes a /metrics endpoint with:

• gateway_requests_total{provider,status} — request counter
• gateway_request_duration_seconds{provider} — latency histogram
• gateway_aip_checks_total{verdict} — integrity check counter
• gateway_cache_operations_total{operation,result} — cache hit/miss
• Standard process_* and nodejs_* metrics

For Kubernetes, enable the ServiceMonitor in values.yaml:

metrics:
  serviceMonitor:
    enabled: true
    interval: 30s

---

Upgrading

Docker Compose

cd smoltbot && git pull
cd deploy/docker
docker compose build
docker compose up -d

Migrations run automatically via the migrate service.

Helm

helm upgrade smoltbot ./deploy/helm/mnemom-gateway \
  --set secrets.existingSecret=smoltbot-secrets

The migration job runs as a pre-upgrade Helm hook.

Always back up your database before upgrading. For Docker: docker compose exec postgres pg_dump -U smoltbot mnemom > backup.sql. For Kubernetes: use your standard PostgreSQL backup procedure.

---

Troubleshooting

Gateway won't start — EnvValidationError

A required environment variable is missing. Check the error message for which variable, then verify your .env file or Kubernetes Secret.

Redis connection refused

• Docker Compose: ensure the redis service is healthy (docker compose ps)
• Kubernetes: verify REDIS_URL in your Secret points to a reachable Redis instance
• Without Redis, the gateway falls back to in-memory KV (single-node only)

License validation failed

• Verify MNEMOM_LICENSE_JWT is set and not expired
• Check /health/ready for the specific license error
• Contact [e-mail] for license reissuance

Upstream LLM API errors (401/403)

• Verify your API keys are correct and have sufficient credits
• The gateway proxies directly to provider APIs — ensure outbound HTTPS (port 443) is allowed
• In Kubernetes, check the NetworkPolicy allows egress to 0.0.0.0/0:443

High memory / OOMKilled

• Increase container memory limits (512Mi minimum, 1Gi recommended for high traffic)
• If using in-memory KV, switch to Redis to reduce memory pressure
• Set NODE_OPTIONS=--max-old-space-size=768 for fine-grained heap control

---

Next steps

• Smoltbot overview — architecture and components
• Enforcement modes — observe, nudge, and enforce
• Observability guide — dashboards and alerting
• Security model — trust boundaries and threat model