Licensing, administration and troubleshooting
Free and Pro, backups, security and sessions, and what to check when something is wrong.
Licensing: Free vs. Pro
- Free: up to 2 active agents, no account or payment needed, works fully offline.
- Pro ($49/yr): unlimited active agents, the Claude, Codex and Grok, agents, terminals and screen-sharing screens on your TVs, and these plugins: Ring Security, Home Control, iMessage Chat, iCloud Mail Cleanup, Slack Desktop, Kubernetes, DeviceLab, Video Studio, Book Studio, Comic Studio and Historical Intelligence. Every install gets a 7-day trial of all of it. After the trial those plugins show an upgrade card (your settings and data are kept) and unlock again with a license. The other plugins, the TV games, the tutorials, recipes, the watch list, the browsers, the image tools and the Morning Briefing stay free.
Settings → License shows your current tier and usage, and has Upgrade/Manage Subscription/Deactivate Device actions. Full details — activation steps, cancellation behavior, what data this involves — are in deploy/README-release.md's Licensing section and deploy/PRIVACY_POLICY.md.
If you're at the Free limit, creating a 3rd agent still works (configurations are never limited) — only enabling it is blocked, with a prompt to upgrade.
Administration
Backups and restore
JunctionBox backs up its database automatically (daily, 14 archives kept by default) and you can trigger one immediately from Settings. A backup includes the database and the encryption key needed to read its encrypted fields — the key is operationally critical: losing ~/.junctionbox/master.key without a backup makes stored credentials (API keys, box passwords, webhook secrets) unrecoverable.
Restoring requires typing the exact archive name, re-entering your password, and refuses to run while any agent run is active — it also takes a fresh safety backup first, so a bad restore is itself recoverable.
Data retention
Settings lets you configure how long completed runs/tasks/logs are kept (independently of each other) and preview what a cleanup would actually delete before running it. Cleanup re-verifies your password and takes a safety backup first, same as restore.
Security and sessions
- Settings shows every active login session (address, device, last activity) and lets you revoke any of them; changing your password revokes all of them at once.
- Every meaningful action (not just logins) is recorded in a secret-free audit log, visible in Settings.
junctionbox-apiitself only ever listens on127.0.0.1— nothing outside this machine can reach it directly, and this never changes. Install sets up a separate, self-signed-HTTPS Caddy proxy in front of it automatically (install-https-proxy.sh, runs as part of install, safe to re-run), reachable athttps://<this machine's LAN IP>:8443(or the next free port, if something else already had 8443) — that's the one thing actually reachable from another device. First visit from a new device shows a one-time certificate warning (self-signed, no public CA) — expected, accept it once. SeeDEPLOYMENT_SECURITY.mdfor the reasoning.
System diagnostics
Settings → system diagnostics reports database health, encryption-key status, storage, and detected local CLI installs — the first place to check if something seems broken, before digging into logs.
Exporting/importing
Settings → Export produces a portable JSON snapshot of agents, evaluations, and schedules (not secrets) you can import into another install.
Troubleshooting
For service-level problems (won't start, port conflicts, logs) see deploy/README-release.md's Troubleshooting section — that covers the systemd/launchd layer underneath JunctionBox, before you even reach the web UI.
Application-level starting points:
- Ask the JunctionBox Support agent — it's specifically built to answer "how do I..." questions and do basic health checks without you needing to find the right doc section.
- Agent won't start / 402 error: you've hit the Free-tier 2-active-agent limit — see Licensing above.
- An agent can't see / delegate to another agent: check they share a Team — delegation is invisible outside shared teams by design, not a bug.
- A local CLI agent (Claude/Codex/Grok) can't reach a file or tool: check its permission profile and working directory — Restricted mode is read-only and Workspace mode only allows its own directory, by design.
- Something seems to be hanging: turn on Stall detection (Settings, off by default) so a stuck run gets flagged with a reason and recovery options instead of running forever.
- Check Settings → system diagnostics and the audit log before assuming something is broken versus working as configured.
Source: USER_GUIDE.md in the public releases repository.

