Tutorials

Install the Agent

Install the Kepeink agent on Linux, macOS, or Windows with a one-line installer and connect it to a tunnel using your agent token.

Install the Agent

The agent is the small program that runs on your machine, dials out to Kepeink, and holds your tunnel open. This page covers installing it and connecting it to a tunnel with your agent token.

Before you start

  1. Sign up and open the dashboard.
  2. Create a tunnel and choose its backend mode (proxy or static) and target.
  3. Copy the agent token the dashboard shows for that tunnel — it looks like kpt_.... The token identifies the tunnel, so keep it secret.

Install as a background service (Linux and macOS)

Run the one-line installer. It downloads the agent, installs it as a system service, and starts it. Paste your token inline so it connects right away:

curl -fsSL https://cdn.kepeink.hu/install.sh | sudo sh -s -- --token=kpt_xxxxxxxx

Without a token, the installer runs and then prompts you for one:

curl -fsSL https://cdn.kepeink.hu/install.sh | sudo sh

The service is named kepeink-agent, starts on boot, and reconnects on its own if the connection drops.

Install on Windows

Run this in an elevated PowerShell session. It downloads and runs the installer with your token:

Invoke-WebRequest -UseBasicParsing https://cdn.kepeink.hu/install.ps1 -OutFile $env:TEMP\kepeink-install.ps1; & $env:TEMP\kepeink-install.ps1 -Token kpt_xxxxxxxx

Run with Docker instead (same tunnel, no host install)

If your app already runs in Docker, add the agent to the same compose project instead of installing it on the host — one service block, no host package:

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:

The named volume matters: /home/nonroot holds the agent's ACME account key, not just its certificate. Recreating the container without it forfeits the renewal exemption, so each restart spends a fresh issuance against a Let's Encrypt per-registered-domain limit shared with every other tunnel on that domain. Do not set KEPEINK_AGENT_DIR yourself — it is already baked correctly, and overriding it is what makes the key ephemeral. To confirm what the image bakes, inspect the registry rather than a local copy: see Run the agent with Docker.

Set KEPEINK_AGENT_TOKEN=kpt_xxxxxxxx in the .env next to your compose file and put the agent on the same Docker network as your app so the tunnel target can use the service DNS name (e.g. http://web:3000, not http://localhost:3000 — inside the agent container localhost is the agent itself). See the full recipe in Run the agent with Docker — including Immich at Expose Immich with Docker.

Quick one-liner without compose:

docker run -d --name kepeink-agent --restart unless-stopped \
  -e KEPEINK_AGENT_TOKEN=kpt_xxxxxxxx registry.kepeink.hu/agent:2

Anonymous pull, multi-arch (amd64/arm64/arm), major-pinned :2. Update by docker compose pull && docker compose up -d kepeink-agent — the image is immutable, so in-container self-update is off by design.

Run in the foreground instead

If you would rather not install a service — for a quick test or a one-off demo — use the run bootstrap. It downloads the agent into the current directory as ./kepeink and runs it in the foreground with human-readable logs:

curl -fsSL https://cdn.kepeink.hu/run.sh | sh -s -- --token=kpt_xxxxxxxx

Stop it with Ctrl-C. Nothing is left installed.

Confirm it is working

Once the agent is running, open your tunnel's assigned hostname from the dashboard in a browser. You should see your local service served over HTTPS. If the page does not load, check that:

  • the local target you configured is actually listening **and reachable from the host that runs the agent** (for Docker: the target must resolve inside the agent container — use http://<service>:<port> on the same Docker network, add extra_hosts: ["host.docker.internal:host-gateway"] for a host-side service, never http://localhost:<port> for a different container), and
  • the agent process is running and shows a connected session in its logs (journalctl -u kepeink-agent -f for the host service, `docker compose logs -f kepeink-agent` for Docker).

Next steps

Get started