-
Notifications
You must be signed in to change notification settings - Fork 1
FAQ
Is AgentPulse stable enough for daily use? The core — sessions, events, dashboard, hooks — is production-quality and dogfooded daily. The AI control plane (watcher, Ask, Telegram) is pre-1.0 and gated behind Labs flags that default off. Breaking changes are possible until 1.0; the CHANGELOG calls them out explicitly.
Does it send data anywhere?
Anonymous usage pings go to telemetry-agentpulse.xmojo.net (Cloudflare Worker + D1). Opt out with AGENTPULSE_TELEMETRY=off. Session contents, API keys, and LLM prompts never leave your instance.
What's the license? MIT.
Do I need Docker?
No — bun run start works against a production build. Docker is the path of least resistance for most users. See Deployment.
Can I run it on a Raspberry Pi?
Yes, if the image supports your architecture — the published image is linux/amd64 today. A PR for multi-arch builds is welcome. The SQLite backend keeps the footprint small (~100MB RAM idle).
Can two users share one instance?
Yes for local accounts (each gets their own /login); Authentik SSO is per-user. Watcher configs aren't scoped per-user today though — HITL approvals are shared, so if your teammate approves a HITL request, the session acts on it. If you need strict per-user isolation, run separate instances.
Why doesn't my remote hook show up?
Claude Code blocks hooks to non-localhost IPs as a security measure. Use curl -sSL https://your-agentpulse/setup-relay.sh | bash -s -- --key ap_your_key instead — it installs a localhost daemon that forwards events to your remote AgentPulse.
Does AgentPulse work with agents other than Claude Code / Codex?
Not out of the box, but any tool that can POST an HTTP hook with an X-Agent-Type header and a reasonable event shape will work. The event processor normalizes fields (src/server/services/event-normalizer.ts) so adding a new agent type means adding a normalizer branch + optional status snippet. PRs welcome.
Why does my dashboard show sessions as "idle" right after they finish?
Sessions enter idle if no Stop event arrives within a few seconds of the last activity. If Stop lands, they go to completed. Working sessions can't go idle until they stop working — a small session state machine in session-tracker.ts enforces that ordering.
Does the watcher work without an internet connection?
Yes if your LLM provider is local (Ollama, LM Studio, llama.cpp server). Point a provider at http://<host>:11434/v1 and use Qwen / Llama / etc. Entirely offline.
The watcher keeps firing — is that normal?
One run per meaningful session event (UserPromptSubmit / Stop / TaskCompleted / plan update / AI error), debounced by 1s per session. If you see >1 per second sustained, that's a bug — check the ai_watcher_runs table for runs with trigger_kind = "manual" (those indicated the old session_updated bug, fixed in 0.2).
Can I trust the watcher to auto-dispatch prompts?
Only if you set the session's policy to auto or ask_on_risk AND the session is in managed mode. Default is ask_always + observed mode, which surfaces every decision as HITL with no auto-actions. See AI Watcher → Policies.
What happens if the LLM hallucinates a destructive prompt?
The dispatch filter rejects it. rm -rf, shell injection patterns, curl | sh, and credential references are hard-coded to require human approval regardless of policy. Test results + other risk classes are configurable.
Why is my first Ollama watcher call slow / failing?
Ollama cold-loads models on first request. 8B models take 3–10s to warm. Set OLLAMA_KEEP_ALIVE=30m on the Ollama side, or pre-warm with ollama run <model> "" before starting sessions.
Why does Ask say "No candidate sessions matched"?
The resolver couldn't find a session whose name / cwd / branch / currentTask matched your query. Try naming the session explicitly ("how's fast-hawk going?"), or use a breadth hint ("across all active sessions") to bypass the keyword requirement.
Why does Ask refuse to stop a session when I ask it to? By design. The Ask assistant is read-only — if it had action permissions we'd need a whole auth-and-audit story. Use the dashboard's Stop button; Ask will tell you that.
Are my Ask conversations sent to the LLM provider? Yes — each turn includes the last ~6 messages of conversation plus the context block (resolved session metadata + recent events). For cloud providers that's real data egress. Use a local Ollama provider if that's a concern.
Why is polling the default? Because most home-lab deployments don't have a public hostname that resolves to a routable IP. Telegram rejects webhook URLs pointing at reserved IPs (192.168.x.x, 10.x.x.x, etc.). Polling works from any network. See Telegram Channel.
Can one bot serve multiple AgentPulse instances? No — each bot's webhook / polling is instance-wide. Run separate bots for separate instances.
The bot answered a HITL once and now it ignores me.
You might have disabled the per-channel askEnabled toggle (Settings → Telegram). That silences free-form messages but keeps HITL delivery active. Flip it back on.
Can I use Postgres instead of SQLite?
Yes, as of v0.4.0. Set DATABASE_URL=postgres://user:password@host:5432/dbname?sslmode=require and AgentPulse uses PostgreSQL. SQLite remains the default when DATABASE_URL is unset or empty.
For Kubernetes deployments, use the deploy/overlays/postgres/ Kustomize overlay — it wires up DATABASE_URL, removes the SQLite backup sidecar, and switches the deployment to RollingUpdate. See deploy/overlays/postgres/README.md and Deployment → Postgres.
Limitations in v0.4.0: vector search (event_embeddings) is SQLite-only; Postgres search uses ILIKE (adequate for moderate volumes; tsvector is a follow-up). There is no SQLite→Postgres data migrator — Postgres installs start fresh.
How do I upgrade?
docker pull && docker-compose up -d (or kubectl rollout restart on k8s). Migrations are idempotent. See Deployment → Upgrades.
Does AgentPulse work behind a reverse proxy other than Traefik?
Yes — nginx, Caddy, Cloudflare Tunnel all work. The only constraint is keeping /api/v1/hooks, /api/v1/hooks/status, /api/v1/channels/telegram/webhook, and /setup*.sh publicly reachable with no SSO layer (they have their own auth).
Can I run it behind Cloudflare with Full (strict) mode?
Yes — use a cert-manager or Cloudflare Origin cert on your ingress. Cloudflare Tunnel also works if you don't want to open ports.
How do I get involved?
10 starter issues are tagged good first issue with file paths + acceptance criteria. Pick one that interests you. See Contributing.
Is there a Discord? Not yet. GitHub Discussions / Issues are the canonical channels today. A Discord would need a moderator first.