# Kepeink

Kepeink makes self-hosted services reachable over HTTPS without port
forwarding: an outbound-only agent on your machine holds a tunnel open to
Kepeink's router plane, which serves the public HTTPS route.

**One document, every host.** This is the same file at
`https://kepeink.hu/llms.txt`, `https://manage.kepeink.hu/llms.txt` and
`https://status.kepeink.hu/llms.txt` — identical bytes, so which hostname
you fetched it from never changes the answer. Every link below is
absolute for the same reason. `llms-full.txt` works the same way on all
three.

## Hosts

| Host | What it is | Auth |
|---|---|---|
| `https://manage.kepeink.hu` | The management API (`/api/v1/*`) and the browser console, which is just a client of it — no privileged UI-only path. Create tunnels, reconfigure them, toggle them, issue and revoke agent tokens. | `Authorization: Bearer kpm_…` |
| `https://kepeink.hu` | Marketing site and human documentation (`https://kepeink.hu/docs`). No API of its own. | none |
| `https://status.kepeink.hu` | Public health of Kepeink's own infrastructure. `GET /api/status` returns the current snapshot as JSON; `GET /api/ping` is a liveness probe returning `ok`. Read-only, no auth, no write endpoints. | none |

Endpoint paths written bare below (`/api/v1/tunnels`, `/api/auth/…`) are
on `https://manage.kepeink.hu` unless stated otherwise. They do **not**
exist on the other two hosts, which redirect unknown paths to their own
home page — so a request to the wrong host answers `200 text/html`, not
a 404. Prefix with the host above rather than relying on where you
fetched this file.

## LLM Quickstart — minimum viable tunnel (4 commands)

Get a key once, through the browser: sign up at `https://manage.kepeink.hu`
(email code or Google OAuth), open **Account & activity → Access tokens**,
and create one. That's the one browser-gated step — the same shape as any
API's "get your key from the dashboard" instruction. Everything below is
plain HTTP.

Prereqs: `KEPEINK_API_KEY=kpm_…` (never invent a key prefix — `kpm_` for
management API, `kpt_` for agent tokens). Every management call is
`Authorization: Bearer $KEPEINK_API_KEY` — no cookies.

```sh
# 1. Verify the key + inspect workspace/role (must be owner/admin/member to create tunnels)
curl -fsS https://manage.kepeink.hu/api/v1/me \
  -H "Authorization: Bearer $KEPEINK_API_KEY" \
  -H "User-Agent: my-automation/1.0"

# 2. Create a proxy tunnel (target must be reachable FROM the agent host)
#    body: { target, backend_mode="proxy"|"static"|"ssh" }
#    proxy target: "http://localhost:3000" | "http://127.0.0.1:8080" | "http://<lan-host>:<port>"
#    static target: "/var/www/dist" (absolute path on agent host)
#    ssh target: "host:22"  (web terminal)
#    response { tunnel_id, sni, public_url, agent_token: "kpt_…" } — agent_token shown ONCE
curl -fsS -X POST https://manage.kepeink.hu/api/v1/tunnels \
  -H "Authorization: Bearer $KEPEINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":"http://localhost:3000","backend_mode":"proxy"}'

# 3a. Host service (systemd): paste the returned kpt_… inline
curl -fsSL https://cdn.kepeink.hu/install.sh | sudo sh -s -- --token=kpt_xxxxxxxx

# 3b. Docker (same compose project as the app — target must resolve INSIDE the agent container):
#     image: registry.kepeink.hu/agent:2 (anonymous pull, multi-arch, major-pinned :2)
#     env: KEPEINK_AGENT_TOKEN=kpt_… (the ONLY required env)
#     target: http://<service-name>:<port> (e.g. http://immich-server:2283), NOT http://localhost:… inside the container
#     host service: http://host.docker.internal:<port> + extra_hosts: ["host.docker.internal:host-gateway"]
#     update: docker compose pull && docker compose up -d kepeink-agent
#     persist: mount a named volume at /home/nonroot (agent data dir; holds the ACME account key — see /llms-full.txt)
#     do NOT set KEPEINK_AGENT_DIR — it is already baked correctly. Pointing it outside your volume makes the ACME
#       account key ephemeral, and each recreate then spends a Let's Encrypt issuance from a per-domain limit SHARED
#       with every other tunnel on that rproxy domain — you would be taking other tenants' certificates, not just yours.
#     verify the image against the REGISTRY, never a local copy:
#       docker buildx imagetools inspect registry.kepeink.hu/agent:2 --format '{{json .Image}}'
#       `docker image inspect` / `docker inspect <container>` read LOCAL state and will describe an image you already
#       replaced. KEPEINK_AGENT_DIR=/tmp with no VOLUME means a pre-2.5.43 copy: re-pull, do not adapt compose to it.

# 4. Verify public routing
curl -fsS https://<sni>/
```

Exact JSON shapes and error codes (403 missing feature, 409 cert_worker conflict on e2e, 429 headroom): `https://manage.kepeink.hu/openapi.json`. Full tunnel/access-gate/custom-domain/e2e options: `https://manage.kepeink.hu/llms-full.txt`. Human tutorials with compose snippets: `https://kepeink.hu/docs/run-the-agent-with-docker`, `https://kepeink.hu/docs/expose-immich-with-docker`, `https://kepeink.hu/docs/end-to-end-tls`.

## Authentication

- Browser users sign in with Google OAuth when configured, by email magic link / 6-digit email code, or by exchanging a `kpm_...` API token at `/api/auth/token-login`.
- Browser sessions use the `__Host-kepeink_session` HttpOnly, Secure, SameSite=Lax cookie.
- API clients and LLM agents should use `Authorization: Bearer kpm_...`; browser automation may use the same token with `/api/auth/token-login`.
- API keys are non-expiring machine tokens. Revoke them from the dashboard when no longer needed.
- API keys inherit the current user's workspace role at creation time. Platform admins on `admin.kepeink.hu` can mint audited `kpm_...` API tokens for active users/workspaces.

## Working with the API

- Use `GET /api/v1/me` first to learn the active workspace, role, and capabilities.
- Tunnel on/off is `POST /api/v1/tunnels/{id}/enabled` (cheap toggle); `PATCH /api/v1/tunnels/{id}` is for config changes.
- Prefer idempotent reads before writes.
- Include a descriptive `User-Agent` for automated clients.
- Destructive or billing-affecting calls — takedown submission, checkout creation, tunnel/domain deletion, token revocation, account deletion — are worth a confirmation step in your own flow before firing.
- A handful of account-security endpoints run only in a browser session: `/api/v1/account/mfa/*` (enrollment needs a live authenticator app), `/api/v1/account/delete*`, `/api/v1/account/export`, and `/api/v1/api-keys` creation itself. A `kpm_...` token gets `403 Forbidden` from these; read-only status (`GET /api/v1/account/mfa`, `GET /api/v1/sessions`) still works.
- Free credit outside the dashboard's reCAPTCHA-gated free-trial button comes from `POST /api/v1/billing/codes/redeem` (capability codes) or a paid checkout via `POST /api/v1/billing/checkouts` — both work from a `kpm_...` token with the owner role.
- **These docs describe the CURRENT release.** If a local artifact — a container image, an installed binary, a cached config — disagrees with what is written here, the artifact is stale far more often than the docs are wrong. Update it and re-check before you change your setup to accommodate it: adapting to a stale artifact bakes yesterday's defaults into a file that outlives them. When you do want to verify a claim, read the authoritative source over the network (the registry, `https://cdn.kepeink.hu/manifest.json`, an API response), not a local copy of it.

## References

Absolute on purpose: this file is served verbatim from both
`https://kepeink.hu/llms.txt` and `https://manage.kepeink.hu/llms.txt`,
so a relative link would resolve to a different host depending on where
you fetched it.

- Full agent guide: `https://manage.kepeink.hu/llms-full.txt` (mirrored at `https://kepeink.hu/llms-full.txt`)
- OpenAPI description: `https://manage.kepeink.hu/openapi.json`
- MCP/WebMCP tool annotations: `https://manage.kepeink.hu/.well-known/mcp-tools.json`
- Dashboard: `https://manage.kepeink.hu/`
- Public abuse report portal: `https://manage.kepeink.hu/report` (`/takedown` remains a compatibility path)
- Human tutorials and use cases: `https://kepeink.hu/docs`
- Public infrastructure status API: `https://status.kepeink.hu/api/status`