docker-compose.yml

services:
  beeperbox:
    # Published multi-arch image (linux/amd64 + linux/arm64) from GHCR.
    # Pin to a specific version for reproducibility, or use :latest to
    # track the newest release. :edge tracks master and may break.
    # To build from a local checkout instead, overlay docker-compose.dev.yml:
    #   docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d
    image: ghcr.io/hamr0/beeperbox:${BEEPERBOX_IMAGE_TAG:-latest}
    # Container name is env-overridable so multiple instances can coexist on
    # one host. Single-instance users get the default "beeperbox" and do not
    # need to set anything. Multi-instance users pass a distinct name per
    # instance alongside BEEPERBOX_HOST_PORT / BEEPERBOX_NOVNC_PORT /
    # BEEPERBOX_MCP_PORT:
    #   BEEPERBOX_CONTAINER_NAME=beeperbox-a docker compose -p beeperbox-a up -d
    container_name: ${BEEPERBOX_CONTAINER_NAME:-beeperbox}
    restart: unless-stopped
    ports:
      # Bound to 127.0.0.1 so the API and noVNC UI are NOT reachable from
      # other hosts by default. For remote access use an SSH tunnel,
      # Tailscale/Wireguard, or a TLS-terminating reverse proxy in front.
      # To expose beyond loopback (NOT RECOMMENDED), drop the 127.0.0.1
      # prefix — and only after setting MCP_AUTH_TOKEN and VNC_PASSWORD
      # below. Those are the only auth on :23375 (MCP) and :6080 (noVNC)
      # once the loopback binding is gone.
      #
      # Host ports are env-overridable so dev machines that already run a
      # native Beeper Desktop on :23373 can fall back without editing the
      # compose file:
      #   BEEPERBOX_HOST_PORT=23374 docker compose up -d
      #   BEEPERBOX_NOVNC_PORT=16080 docker compose up -d
      - "127.0.0.1:${BEEPERBOX_NOVNC_PORT:-6080}:6080"
      - "127.0.0.1:${BEEPERBOX_HOST_PORT:-23373}:23380"
      - "127.0.0.1:${BEEPERBOX_MCP_PORT:-23375}:23375"
    environment:
      # Bearer token for the Beeper Desktop API. Created in Beeper's
      # Settings -> Developers panel after first login. Required for
      # the MCP server to call /v1/* endpoints — without it, only the
      # raw API on :23373 is reachable (and even that needs the token
      # for everything except /v1/info).
      BEEPER_TOKEN: ${BEEPER_TOKEN:-}
      # Optional bearer token for the MCP HTTP transport (:23375). When set,
      # every MCP HTTP request must send `Authorization: Bearer <token>`.
      # Leave empty to keep the transport open and rely on the loopback
      # publish above. The stdio transport (docker exec -i … --stdio) is
      # local-only and unaffected. Host/Origin are always validated against
      # loopback to block DNS-rebinding; set MCP_ALLOWED_HOSTS for a reverse
      # proxy in front (e.g. MCP_ALLOWED_HOSTS=mcp.example.com).
      MCP_AUTH_TOKEN: ${MCP_AUTH_TOKEN:-}
      MCP_ALLOWED_HOSTS: ${MCP_ALLOWED_HOSTS:-}
      # Optional password for the noVNC/VNC session (:6080). When set, x11vnc
      # requires VNC authentication instead of serving an open session. Leave
      # empty to keep the password-less one-time-login flow (safe only while
      # :6080 stays loopback-only, the default above).
      VNC_PASSWORD: ${VNC_PASSWORD:-}
      # Optional path for the echo-guard sent-message ledger (lets poll_messages
      # / read_chat mark the agent's own API sends source:"api"). Leave empty to
      # use the per-user default under the config volume below
      # (/root/.config/beeperbox/sent-ledger.json — homedir is /root in the
      # container) — only override to relocate it. Best-effort: a failed write
      # degrades the guard to in-memory, never fails a send.
      BEEPERBOX_SENT_LEDGER: ${BEEPERBOX_SENT_LEDGER:-}
    volumes:
      - beeperbox_config:/root/.config
    shm_size: '256m'
    # Defense-in-depth: the container runs Beeper Desktop (Electron) as root
    # with --no-sandbox, so block setuid privilege escalation. This is safe
    # because nothing in the stack relies on setuid to escalate; it just
    # shrinks the blast radius of a renderer compromise. (A full non-root +
    # Chromium-sandbox rebuild was considered and rejected as too fragile for
    # a single-tenant container that already trusts Beeper Desktop.)
    security_opt:
      - no-new-privileges:true

volumes:
  beeperbox_config: