The Heypi admin panel is a lightweight web UI served underDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/hunvreus/heypi/llms.txt
Use this file to discover all available pages before exploring further.
/admin/*. It is disabled by default and shares the same HTTP listener as the Slack HTTP mode and webhook adapters. Enable it with a single option in your createHeypi config:
127.0.0.1:3000. On loopback, Heypi logs a one-time login URL at startup that expires after five minutes.
Admin Pages
/admin
Chats view with recent threads and a timeline for the selected thread.
/admin/threads/:id
Full thread timeline showing user, assistant, approval, and tool activity.
/admin/approvals
Pending approvals list, paged with a maximum of 50 per page.
/admin/jobs
Scheduled jobs configured through app-level
jobs, paged at 50 per page./admin/memory
Read-only, paged memory file table with escaped file contents. Useful for
memory.scope: "user" agents where each user has a separate file./admin/configuration
Summary of agent, model, runtime, HTTP, adapter, memory, and process start configuration.
Authentication
- Default (one-time link)
- Local dev only (no auth)
- Production
On loopback, Heypi logs a one-time login URL when it starts. The link expires after five minutes.If it expires while the process is still running, mint a fresh one from the CLI:This reads
server.<pid>.json and the local admin secret, signs a short-lived canonical-state-root-scoped URL, and prints it. The --state, --url, and --pid flags are available for non-default setups.heypi admin link
The admin link CLI command mints a fresh one-time login URL from local admin state without contacting the running server:
| Flag | Description |
|---|---|
--state <path> | Path to the Heypi state directory. Auto-discovered if omitted. |
--url <url> | Override the descriptor URL, e.g. through a tunnel or proxy. Still probed against the descriptor instance ID. |
--pid <pid> | Select one descriptor when multiple instances share the same state root. |
--json | Print { url, expiresAt } as JSON instead of just the URL. |
Live Updates
The browser opens a Server-Sent Events stream at/admin/events. Overview counters update live. List pages refresh when the server-side revision changes. Thread pages only refresh when the selected thread changes.
Security Notes
Reserved route prefix
Reserved route prefix
/admin is a reserved route prefix. Non-admin adapters cannot register routes under it.Sessions
Sessions
Sessions are opaque random tokens stored only as hashes in process memory. They are never written to disk.
One-time login links
One-time login links
Links are HMAC-signed with the local admin secret, scoped to the canonical state root, expire quickly (default 5 minutes), and are single-use within the running process. A process restart clears the in-memory used-link cache, but unexpired links still expire by timestamp.
Auth boundary
Auth boundary
state.root is the admin auth boundary. Use a separate state root per agent when login access should be separated. Admin activity, approvals, and calls are filtered by agent when a database is shared.Memory display
Memory display
Memory is shown as escaped text, not rendered Markdown. Contents are treated as untrusted data.
Static assets
Static assets
Admin CSS and JavaScript are served locally from
/admin/assets/*. The admin panel does not load any UI assets from a CDN.CSRF protection
CSRF protection
Unsafe actions require a CSRF token and same-origin check.
<state.root>/admin/secret holds generated local admin signing material.
Keep the state/ directory private and do not commit it to version control.
<state.root>/admin/server.<pid>.json holds non-secret listener discovery
data (including the instance ID the CLI uses to reject stale descriptors). It
is written only after the HTTP listener has a real port.v1 does not include: chat-issued admin links, approval execution from the
web UI, config editing, secret editing, or shell access. Approve or reject
requests from the original chat provider.