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

> Learn to deploy ai-memory behind a reverse proxy for secure HTTPS TLS termination. Configure Nginx Caddy or Traefik for robust protection and easy management.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: how-to-guide
- Published: 2026-08-20

---

**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`](https://github.com/akitaonrails/ai-memory/blob/main/docs/https-via-proxy.md) and [`docs/deploy.md`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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:

```bash
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`](https://github.com/akitaonrails/ai-memory/blob/main//etc/nginx/conf.d/ai-memory.conf):

```nginx
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`](https://github.com/akitaonrails/ai-memory/blob/main/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`:

```caddy
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`](https://github.com/akitaonrails/ai-memory/blob/main/docker-compose.yml) referencing patterns from [`docker/multiuser-test/README.md`](https://github.com/akitaonrails/ai-memory/blob/main/docker/multiuser-test/README.md):

```yaml
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:

```yaml
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`](https://github.com/akitaonrails/ai-memory/blob/main/SECURITY.md) and [`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/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`):

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

```

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

```ini
[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:

```bash
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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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.