Compose bind-mounts ZONE_HOST_ROOT at /host in the manager. Workspace Folders (and the first-run setup step) store host paths under that root; chat tools then open the matching /host/... path as the zone user. Mounting $HOME makes every file under home reachable from any chat in any workspace. Pick the smallest parent that covers the folders you will select. Recreate the manager after changing ZONE_HOST_ROOT. An empty value mounts ./.zone/host-empty, so nothing on the host is visible until a root is set.

Traefik requires access to the Docker socket (/var/run/docker.sock) to:

• Automatically discover containers and configure routes
• Read container labels for routing configuration
• Monitor container lifecycle events

Security Implications: Access to the Docker socket is equivalent to root access on the host system. A compromised Traefik container could:

• Start/stop any container
• Read secrets from any container
• Escalate privileges
• Access host filesystem

Use a socket proxy like tecnativa/docker-socket-proxy to limit Docker API access:

services:
  docker-proxy:
    image: tecnativa/docker-socket-proxy:latest
    container_name: docker-proxy
    restart: unless-stopped
    environment:
      - CONTAINERS=1  # Allow listing containers
      - NETWORKS=1    # Allow listing networks
      - SERVICES=0    # Deny services access
      - TASKS=0       # Deny tasks access
      - POST=0        # Deny POST (create/update)
      - DELETE=0      # Deny DELETE
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - internal

  traefik:
    # ... existing config ...
    volumes:
      # Replace socket mount with proxy connection
      - docker-proxy:2375  # Instead of /var/run/docker.sock
    environment:
      - DOCKER_HOST=tcp://docker-proxy:2375

The current configuration mounts the Docker socket as read-only (:ro). This is acceptable for:

• Development environments
• Self-hosted setups where the host is already trusted
• Environments where Traefik is the only entry point

Justification for Current Approach:

1. Traefik is a trusted, widely-used reverse proxy
2. The socket is mounted read-only
3. Traefik runs on an isolated Docker network
4. The project is designed for self-hosted, single-user deployments

1. Keep Traefik updated to patch security vulnerabilities
2. Review Traefik configuration regularly
3. Monitor Traefik logs for suspicious activity
4. Consider using a socket proxy in production deployments
5. Restrict network access to the Traefik container

• Docker Socket Security
• Traefik Security Documentation
• Docker Socket Proxy Project

The default configuration includes fallback passwords for development:

• PostgreSQL: litellm_password
• LiteLLM Master Key: sk-dev-insecure-key-change-for-production
• SearXNG Secret: dev-insecure-key-change-for-production

CRITICAL: These MUST be changed for any production or internet-accessible deployment.

Use the provided setup script to generate secure credentials:

./scripts/setup.sh

Or manually generate secure keys:

# Generate 32-byte base64 keys
openssl rand -base64 32

The zone_internal network is designed to isolate:

• Ollama (LLM backend)
• PostgreSQL database
• LiteLLM proxy
• SearXNG search engine

Configuration: Set internal: true to prevent external access:

networks:
  internal:
    internal: true  # Blocks all external traffic

Note: The current configuration has internal: false to support certain deployment scenarios. Review your threat model and adjust accordingly.

The zone_edge network connects:

• Traefik (reverse proxy)
• Zone console (chat and workspace interface)
• LiteLLM (API gateway)
• Manager API

Only Traefik should have ports exposed to the host.

Traefik uses HTTP Basic Authentication for:

• Manager interface (manager.${DOMAIN_HOST_WEBUI})
• Traefik dashboard (traefik.${DOMAIN_HOST_WEBUI})

Credentials are stored in ./auth/users.htpasswd using bcrypt hashing.

Zone chat uses Manager's account authentication and workspace access controls. Chat history and agent actions belong to the authenticated user's workspace.

LiteLLM requires API key authentication via SECURITY_LITELLM_MASTER_KEY.

Master Key Distribution: The master key is shared with:

1. LiteLLM - API gateway (generates the key)
2. Manager - Backend model registration and inference requests

This distribution is minimized to only services that require it. The key is:

• Not exposed to the host
• Not exposed via environment variables to untrusted containers
• Transmitted only over internal Docker networks
• Never logged or stored in application logs

TOOL_RUNNER_PROXY_URL sets proxy environment variables for command tools and MCP subprocesses after their normal environment overlays. VPN launches configure Gluetun's HTTP proxy. Proxy-aware clients fail if that configured proxy is unavailable; loopback and internal service destinations bypass it. This covers clients that honor the proxy environment, not raw sockets or clients that ignore it. SearXNG handles chat search queries; generic tool HTTP requests use Gluetun's proxy directly.

LiteLLM is configured to NOT store prompts in spend logs by default:

general_settings:
  store_prompts_in_spend_logs: false  # Privacy-first configuration

SearXNG routes search traffic through VPN (when enabled) to:

• Mask IP addresses from search providers
• Prevent search tracking
• Enable access to region-restricted content

Enable automatic TLS certificates:

SECURITY_GENERATE_CERTIFICATE=true
SECURITY_HTTP_REDIRECT=true
ADVANCED_ACME_EMAIL=your-email@example.com

Requirements:

• Valid public domain
• Ports 80/443 accessible from internet
• Domain points to your server

For local development, use self-signed certificates or accept HTTP connections.

Custom containers (Manager) should run as non-root users. The Dockerfiles have been updated to include:

USER nonroot:nonroot

Regularly update Docker images to patch security vulnerabilities:

docker compose pull
docker compose up -d

If you discover a security vulnerability, please report it responsibly:

1. Do NOT open a public GitHub issue
2. Email the project maintainer with details
3. Allow time for a patch before public disclosure

Before deploying to production:

• Change all default passwords and secrets
• Enable TLS with valid certificates
• Review network isolation settings
• Disable unnecessary services
• Configure firewall rules
• Verify Manager authentication and workspace access
• Restrict signup or user registration
• Review prompt logging settings
• Update all Docker images
• Configure automated backups
• Set up monitoring and alerting
• Review Docker socket security
• Test authentication on all endpoints
• Validate secret key entropy