Configuration

Configure the self-hosted proxy with environment variables or command-line flags. A flag overrides its environment variable. The proxy also reads a .env file from its working directory, if there is one.

The desktop app’s Local Proxy is configured in the app instead. See the quickstart.

Reference

Both timeouts must be at least 1 second. Run maple-proxy --help for the list built into your version, and maple-proxy --version to print the version.

Example with flags:

maple-proxy --host 0.0.0.0 --port 8080 --backend-url https://enclave.trymaple.ai

Backend and trust roots

Leave MAPLE_BACKEND_URL and MAPLE_PCR0_ENVIRONMENT at their defaults to use Maple’s production service.

The trust roots must match the backend. Maple’s development enclave needs the development roots, and you must select them explicitly:

maple-proxy --backend-url https://enclave.secretgpt.ai --pcr0-environment development

If the roots don’t match the backend, attestation fails and /v1 requests return 502.

Timeouts and retries

Both timeouts default to five minutes.

• MAPLE_REQUEST_TIMEOUT_SECS covers sending a request through to the end of a non-streaming response. For a streaming response, it covers only the time until the stream starts.
• MAPLE_STREAM_IDLE_TIMEOUT_SECS then limits the wait for each next chunk of a stream. It doesn’t limit the total length of the stream.

A timeout before the response starts returns 504. After the response has started, a timeout ends the body with an error. The proxy doesn’t retry timed-out requests.

The proxy doesn’t retry failed requests either, with one narrow exception inside Maple’s Rust SDK. If the backend reports that the encrypted session has expired, or that it couldn’t decrypt the request, the SDK opens a fresh verified session and resends the request once. That signal isn’t authenticated, so in rare cases a request could run twice. Don’t rely on the proxy for exactly-once execution.

Provider-cache continuity

MAPLE_CACHE_NAMESPACE_ROOT is a client-side secret that keeps provider-cache entries stable when the proxy restarts. Cache hits can make repeated long prompts cheaper and faster.

Generate it once and keep it in your secret manager:

openssl rand -base64 32

It must be standard padded base64 of exactly 32 bytes; the command above produces that. Never log or commit it.

If you leave it unset, the proxy generates a new value each time it starts and logs a warning. Requests still work, but cache hits from earlier runs are lost.

Logging

The proxy logs at info level by default. MAPLE_DEBUG=true (or -d) raises it to debug. You can also set RUST_LOG, for example RUST_LOG=info,maple_proxy=debug.

API keys aren’t written to the logs. The cache namespace root is redacted.

Docker

The image ghcr.io/mapleprivacylabs/maple-proxy sets these defaults:

The image runs as a non-root user and has a built-in health check on /health.

Docker Compose

services:
  maple-proxy:
    image: ghcr.io/mapleprivacylabs/maple-proxy:latest
    container_name: maple-proxy
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      - MAPLE_BACKEND_URL=https://enclave.trymaple.ai
      - MAPLE_REQUEST_TIMEOUT_SECS=300
      - MAPLE_STREAM_IDLE_TIMEOUT_SECS=300
      - RUST_LOG=info
      # Stable secret for provider-cache continuity. Keep it out of source control.
      # - MAPLE_CACHE_NAMESPACE_ROOT=${MAPLE_CACHE_NAMESPACE_ROOT}
      # Only for private deployments where every caller is trusted:
      # - MAPLE_ENABLE_CORS=false
      # - MAPLE_API_KEY=${MAPLE_API_KEY}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 3s
      retries: 3

Production checklist

• Don’t set MAPLE_API_KEY on a shared or public deployment. Each client should send its own key.
• Keep secrets in environment variables or a secrets manager, never in the Compose file.
• Set MAPLE_CACHE_NAMESPACE_ROOT so restarts keep cache continuity.
• Monitor /health for liveness, and a keyed /v1/models call for the full path.
• Put TLS in front of the proxy if traffic to it leaves the machine.