Agent Integrations & Credentials Map¶
The one place to answer "how does the agent connect to X, and where's the
credential?" Every external system Forge agents touch, its auth method, the
secret file (values live only in ~/.forge-secrets/*.env, chmod 600, never in
git), and the helper/script to use. Don't hand-roll new auth, reuse the helper
listed here. Deeper per-system docs are linked in the last column.
Google (Drive / Sheets / Gmail / Calendar) , the agent's primary reach¶
| What | Auth | Secret file | Use via | Detail |
|---|---|---|---|---|
| Personal account ([email protected]) | user OAuth refresh token (acts as Justin) | google-oauth.env |
forge_google_user.user_token("personal") |
reference_google_access |
| Business account ([email protected]) | user OAuth refresh token | google-oauth-business.env |
forge_google_user.user_token("business") |
same |
| Service account (limited) | SA JSON key (JWT) | google-sa.json |
forge_google_sa.sa_token(scopes) |
redundant now; finance SA |
| Legacy calendar client | OAuth refresh (fallback only) | google-calendar.env |
forge_google_calendar.GCal (prefers user token) |
being phased out |
| Gmail mailbox import | IMAP app password (not OAuth) | gmail-import.env |
forge_mbox_to_gmail.py |
independent |
Both user accounts grant full Drive/Sheets/Gmail(read/draft/send)/Calendar,
self-refreshing, unattended. One "Forge Agent" Desktop OAuth client in the
Forge GCP project (1031945499547). The old forge-second-brain business
project was shut down 2026-06-08.
n8n , workflow orchestration (user-context Google/webhooks)¶
- LXC CT 106; auth/secrets in
n8n.env; workflows + creds in n8n's own encrypted DB. Use for user-context outbound actions or node-based flows; trigger via webhook. Currently no active Google workflows (those creds are orphaned; Google work runs throughforge_google_userinstead). Detail: reference_n8n_state,infra/n8n,ssh n8n.
Finance data¶
| What | Auth | Secret file | Use via |
|---|---|---|---|
| SimpleFIN (bank feed, read-only) | claimed access URL | simplefin.env |
forge_simplefin_client.SimpleFIN |
| ERPNext (books, CT 104) | API key/secret | erpnext.env |
forge_erpnext_* (erp-migration agent) |
| Shared transaction lake | n/a (local sqlite) | data/finance/finance.db |
forge_finance_ingest.ingest_rows for external rows |
Infra & surfaces¶
| System | Auth | Secret file | Use via / Detail |
|---|---|---|---|
| Cloudflare (tunnels/DNS/Access) | API token + account id | cloudflare.env |
forge_cloudflare_cf.py, reference_cloudflare |
| Notion | DECOMMISSIONED 2026-07-03 | n/a | forge_notion_api.py deleted; see project_notion_decommission_complete, playbook archived at _archive/superseded-2026-07-09/notion-api-playbook.md |
| Home Assistant | long-lived token | home-assistant.env |
reference_ha_api |
| GitHub | PAT | github.env |
gh CLI / API |
| Plex | token | plex.env |
reference_media_server_stack |
| MikroTik switch | API creds | mikrotik-crs328.env |
reference_mikrotik_crs328 |
Telegram bot fleet (one token per bot, single long-poller each)¶
telegram-inbox-capture.env, telegram-lifeos-coordinator.env,
telegram-notify-outbound.env, telegram-remote-bridge.env,
telegram-general-purpose.env, telegram-autoagent-reporter.env. Detail:
telegram bot playbook,
notify. Never run two pollers on one token.
Other API creds¶
Hevy (hevy.env), USDA (usda.env), wellness (wellness.env), MyAnonaMouse
(mam.env), seerr SMTP (seerr-smtp.env), browser stream (forge-browser.env),
Alexa webhook (forge-alexa-webhook.env), Copper API, Mark's self-hosted LLM
(markaiapi.env, bare key no VAR=; OpenAI chat completions; quirks + limits:
reference_copper_api_mark).
Rules¶
- Secrets only in
~/.forge-secrets/*.env(chmod 600) or n8n's encrypted DB, never in git, never echoed. - New integration = add a row here + its own
reference_*.mdif non-trivial. - Reuse the listed helper; don't write a second auth path for a system that already has one.
[Claude Code, 2026-06-08]