Skip to content

Getting Started

Jump to bottom
jstuart0 edited this page Apr 24, 2026 · 1 revision

Getting Started

Get AgentPulse running and stream your first Claude Code / Codex session into it in ~5 minutes.

1. Run AgentPulse

The fastest path is Docker with auth disabled (safe for local-only use):

docker run -d \
  --name agentpulse \
  -p 3000:3000 \
  -v agentpulse-data:/app/data \
  -e DISABLE_AUTH=true \
  ghcr.io/jstuart0/agentpulse:latest

That's it. Open http://localhost:3000 — you'll see an empty dashboard with a Getting Started card.

Running it on a server you want to access remotely? See Deployment for the Authentik SSO + Traefik setup the reference k8s manifests use.

2. (Optional) Sign in

If you ran with DISABLE_AUTH=true, skip this.

If you ran without that flag, the dashboard will redirect to /login. Because this is the first user on the instance, signup auto-enables and the account you create becomes the admin.

3. Mint an API key (if auth is on)

The Dashboard's Getting Started card has an inline "Create new key" field — pick a name (like macbook-pro) and hit Create. The key is displayed once, copy it somewhere safe.

If DISABLE_AUTH=true you can skip this — hooks don't need a key.

4. Wire up an agent

One-liner from the Dashboard card (paste it into your agent's terminal):

curl -sSL http://localhost:3000/setup.sh | bash -s -- --key ap_your_key

That writes:

  • ~/.claude/settings.json with hook entries that POST to your AgentPulse.
  • ~/.codex/hooks.json (if Codex is installed).

Remote server? Claude Code blocks hooks to non-localhost IPs as a security measure. The relay handles that — use setup-relay.sh instead:

curl -sSL https://your-agentpulse/setup-relay.sh | bash -s -- --key ap_your_key

It installs a localhost daemon that forwards events to your remote AgentPulse. On macOS it auto-starts via LaunchAgent.

5. Start an agent

Open Claude Code or Codex in any project. Within seconds you'll see a new session card appear on the Dashboard with the project name, agent type, and a live activity count. Click in for the full transcript + timeline.

6. What next?

  • Enable the AI watcher — Settings → AI. Paste an LLM provider (Anthropic / OpenAI / Ollama / LM Studio / etc.), flip Labs → AI features on, enable watcher per-session.
  • Connect Telegram — Settings → Telegram. Paste a bot token from @BotFather, pick polling mode (works from any network), enroll a chat by scanning the QR. HITL approvals + conversational Ask land in your phone. See Telegram Channel.
  • Try Ask — Settings → Labs → Ask assistant. Then /ask becomes a chat panel over your live session state. See Ask Assistant.

Troubleshooting

Dashboard is empty after setup.sh

  • Check hook install: cat ~/.claude/settings.json — should have a hooks key pointing at your AgentPulse URL.
  • Run curl -X POST http://localhost:3000/api/v1/health — should return {"status":"ok"}.
  • Check the AgentPulse container logs for POST /api/v1/hooks entries.

Remote hooks not arriving

  • Claude Code blocks non-localhost hook URLs. Use setup-relay.sh instead of setup.sh.
  • Check the relay daemon is running: launchctl list | grep agentpulse on macOS.

Authentik / SSO deployment

  • See Deployment for the Traefik forwardauth + wildcard-cert setup.
  • The /api/v1/hooks path must remain publicly reachable (no Authentik middleware) — hooks authenticate via API key.

Clone this wiki locally