Run the agent with Docker

If your app already uses Docker Compose, add one agent service to the same project. The agent needs outbound network access; your app needs no published inbound port for Kepeink.

Before you start

Note your app's Compose service name and port. For a service named web on port 3000, the tunnel target is http://web:3000. Inside the agent container, localhost refers to the agent container itself.

1. Create the tunnel

In the dashboard, create a proxy tunnel with that target. Copy its kpt_… agent token and keep it private.

2. Add the agent

Add this to the same compose.yml as your app (or an override file in the same project):

services:
  kepeink-agent:
    image: registry.kepeink.hu/agent:2
    restart: unless-stopped
    environment:
      KEPEINK_AGENT_TOKEN: ${KEPEINK_AGENT_TOKEN}
    volumes:
      - kepeink-agent-data:/home/nonroot

volumes:
  kepeink-agent-data:

Put KEPEINK_AGENT_TOKEN=kpt_xxxxxxxx in the project's .env, then run:

docker compose up -d kepeink-agent

The named volume keeps the agent's certificate and ACME account key across container recreations. Keep the image's default data directory; do not set KEPEINK_AGENT_DIR.

3. Check the URL

Open the tunnel's assigned HTTPS URL. If it does not load, check docker compose logs kepeink-agent and confirm the target resolves from the agent's network.

App location	Tunnel target	Agent network
Same Compose project	http://web:3000	Shared by default
On the Docker host	http://host.docker.internal:3000	Add extra_hosts: ["host.docker.internal:host-gateway"] to the agent service
Another Compose project	http://web:3000	Attach the agent to that project's network

To refresh the image later, run docker compose pull kepeink-agent && docker compose up -d kepeink-agent. For a worked example, see Expose Immich with Docker.