# Kepeink

Kepeink gives an app on your own machine a stable public HTTPS URL. The agent connects out, so it works behind CGNAT or LTE with no port forwarding, no public IP, and no domain to buy. You pay for the traffic you use.

Example: `http://localhost:8080 → https://abc-def-ghi.rproxy.94000003.xyz` (the dashboard assigns the actual hostname).

**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 (a check with `"probed": false` is not a measurement); `GET /api/providers` returns what Cloudflare, Hetzner and Creem report on their own status pages for the parts Kepeink uses, with freshness and a per-provider `stale`/`error`, and never affects `/api/status`; `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; Google sign-in appears only when enabled in `/api/auth/config`), 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"|"files"|"vnc" }
#    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)
#    files target: "/srv/shared" (absolute folder; enable tunnel Basic auth and add a user before the agent serves it)
#    Remote Desktop (backend_mode="vnc") target: "desktop" for built-in local hosting, or "host:5900" for an external server. Basic auth strongly recommended; without a user, send agent_config.public_access_acknowledged=true or the agent keeps it unavailable.
#    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`
- Upstream provider status (as reported by the providers): `https://status.kepeink.hu/api/providers`