How to Deploy ai-memory Behind a Reverse Proxy with HTTPS/TLS Termination

TLDR: Deploy ai-memory by binding it to a local loop-back address (default 127.0.0.1:49374) and placing a reverse proxy such as Nginx, Caddy, or Traefik in front to handle TLS termination, HTTPS certificates, and optional authentication.

The ai-memory project from akitaonrails/ai-memory is a self-contained Rust binary designed to run behind a reverse proxy for production deployments. Because the application intentionally listens only on loop-back interfaces by default, you must front it with a proxy that terminates TLS and forwards plain HTTP traffic to the local port. This guide walks through the exact architecture and configuration files documented in docs/https-via-proxy.md and docs/deploy.md to deploy ai-memory securely with HTTPS.

Architecture Overview

The ai-memory binary follows an immutable, single-process design that delegates all TLS handling to the reverse proxy layer. According to docs/ARCHITECTURE.md, the application binds exclusively to 127.0.0.1:49374 (or a configurable loop-back address via AI_MEMORY_BIND) to ensure it never directly handles raw TLS traffic or exposes private keys.

This architecture consists of three layers:

• ai-memory binary – Runs on the host listening only on the loop-back interface, handling web UI and JSON API requests via plain HTTP.
• Reverse proxy – Accepts inbound HTTPS connections, terminates TLS using certificates from Let's Encrypt or custom providers, and forwards traffic to the binary.
• Environment configuration – The binary reads settings like AI_MEMORY_AUTH_TOKEN from environment variables, while the proxy manages SSL certificates, request routing, and optional authentication layers such as Basic Auth or OAuth.

As noted in SECURITY.md, keeping TLS termination at the proxy prevents accidental exposure of cryptographic material and allows the binary to remain stateless and immutable.

Reverse Proxy Configuration Examples

All configurations below assume the binary is launched with:

AI_MEMORY_BIND=127.0.0.1:49374 AI_MEMORY_AUTH_TOKEN=mytoken ai-memory

Nginx Configuration (Flexible TLS Control)

For production environments requiring fine-grained SSL control, Nginx provides the most flexible configuration. Create /etc/nginx/conf.d/ai-memory.conf:

server {
    listen 443 ssl http2;
    server_name ai-memory.example.com;

    ssl_certificate     /etc/ssl/certs/your_cert.crt;
    ssl_certificate_key /etc/ssl/private/your_key.key;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;

    # Optional basic auth

    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.htpasswd_ai_memory;

    location / {
        proxy_pass http://127.0.0.1:49374;
        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_http_version 1.1;
        proxy_set_header Connection "";
    }
}

Reference docs/https-via-proxy.md for details on header forwarding requirements.

Caddy Configuration (Automatic HTTPS)

Caddy automates TLS certificate provisioning via Let's Encrypt with zero configuration. Create a Caddyfile:

ai-memory.example.com {
    reverse_proxy 127.0.0.1:49374
    # Caddy automatically provisions TLS via Let's Encrypt

}

This configuration automatically handles HTTPS redirection and certificate renewal without additional directives.

Traefik with Docker Compose (Dynamic Routing)

For containerized deployments, Traefik provides dynamic service discovery. Below is a partial docker-compose.yml referencing patterns from docker/multiuser-test/README.md:

services:
  ai-memory:
    image: ghcr.io/akitaonrails/ai-memory:latest
    environment:
      - AI_MEMORY_BIND=127.0.0.1:49374
    expose:
      - "49374"

  traefik:
    image: traefik:v2.11
    command:
      - "--entrypoints.websecure.address=:443"
      - "--providers.docker=true"
      - "--certificatesresolvers.myresolver.acme.email=you@example.com"
      - "--certificatesresolvers.myresolver.acme.storage=/letsencrypt/acme.json"
    ports:
      - "443:443"
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock:ro"
      - "./letsencrypt:/letsencrypt"

Add the dynamic configuration to route traffic:

http:
  routers:
    ai-memory:
      rule: "Host(`ai-memory.example.com`)"
      entryPoints:
        - websecure
      service: ai-memory
      tls:
        certResolver: myresolver
  services:
    ai-memory:
      loadBalancer:
        servers:
          - url: "http://ai-memory:49374"

Traefik automatically acquires and renews TLS certificates while forwarding decrypted traffic to the ai-memory container.

Security Considerations

When you deploy ai-memory behind a reverse proxy with HTTPS/TLS termination, follow these security practices from SECURITY.md and docs/ARCHITECTURE.md:

• Bind exclusively to loop-back – Always set AI_MEMORY_BIND to 127.0.0.1:49374 or another local address to prevent direct internet exposure.
• Terminate TLS only at the proxy – The binary never receives encrypted traffic, eliminating the risk of certificate leakage from the application process.
• Proxy authentication forwarding – If you enable AI_MEMORY_AUTH_TOKEN, the reverse proxy can forward the Authorization header unchanged while optionally enforcing additional layers like Basic Auth or OAuth2 at the edge.
• Header sanitization – Ensure your proxy sets X-Forwarded-For and X-Real-IP so ai-memory can log actual client IPs rather than the proxy's internal address.

Production Systemd Service Setup

For bare-metal or VM deployments, run ai-memory as a systemd service with environment variables isolated in a secure file.

Create /etc/ai-memory/.env (ensure permissions are 600):

AI_MEMORY_BIND=127.0.0.1:49374
AI_MEMORY_AUTH_TOKEN=super-secret-token

Create /etc/systemd/system/ai-memory.service:

[Unit]
Description=ai-memory service
After=network.target

[Service]
EnvironmentFile=/etc/ai-memory/.env
ExecStart=/usr/local/bin/ai-memory
Restart=on-failure
User=ai-memory
Group=ai-memory
CapabilityBoundingSet=CAP_NET_BIND_SERVICE

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now ai-memory

Summary

• ai-memory is designed to run behind a reverse proxy, binding only to 127.0.0.1:49374 by default as documented in docs/ARCHITECTURE.md.
• TLS termination occurs entirely at the proxy layer (Nginx, Caddy, or Traefik), keeping the Rust binary simple and stateless.
• Configuration relies on environment variables like AI_MEMORY_BIND and AI_MEMORY_AUTH_TOKEN, never requiring certificate paths in the application.
• Security depends on loop-back binding and proxy-level authentication to prevent unauthorized direct access to the binary.

Frequently Asked Questions

Does ai-memory support native HTTPS/TLS termination?

No. The binary intentionally does not support native TLS termination. According to docs/https-via-proxy.md, the application is designed to run behind a reverse proxy that handles all HTTPS encryption and certificate management, keeping the single-process Rust binary immutable and free of cryptographic state.

What is the default bind address for ai-memory?

The default bind address is 127.0.0.1:49374. You can override this by setting the AI_MEMORY_BIND environment variable, though production deployments should always use a loop-back address to ensure external traffic must route through the reverse proxy.

How do I enable authentication when behind a reverse proxy?

Set the AI_MEMORY_AUTH_TOKEN environment variable when launching the binary. The reverse proxy can then forward the Authorization header to the backend, or enforce its own authentication layer (such as Basic Auth in Nginx or OAuth middleware in Traefik) before forwarding requests to ai-memory.

Can I run ai-memory without a reverse proxy?

While possible for local development by binding to 0.0.0.0, running without a reverse proxy in production is strongly discouraged. SECURITY.md recommends always placing the service behind a proxy to handle TLS termination, request logging, and authentication, as the binary itself provides no encryption or advanced access controls.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}