Connectors

Connectors bridge external services to the box filesystem. They are configured per-box in _config/connectors/.

Credentials

Credentials do NOT live in this box. How keys are stored, requested, and used from code you write is in the agent guide's "API keys & secrets" section; this section adds only what is specific to connectors.

• Google services use shared OAuth tokens plus the box's googleServices policy in _config/box.json.

• To use a granted key from code you write that runs outside the server (a scheduled script, a procedure step), resolve it by name at call time over the loopback API; it needs a grant at agent access, and the value lives in a local variable for the length of the outbound call and is never stored:

  curl -sS -X POST "$BBX_SERVER_URL/$BBX_BOX_NAME/api/secrets/resolve" \
    -H "Authorization: Bearer $BBX_AGENT_TOKEN" -H "Content-Type: application/json" \
    -d '{"name":"<secret-name>","purpose":"<short-label>"}'
  # -> {"value":"…","suspect":false}
  

  A trick declares its secrets in secrets.json instead and receives them in its environment; see tricks.md.

• Built-in connectors (Gmail, Calendar, Drive, transcription, …) resolve their own credentials inside the server process. You never see or need those values.

• A scheduled script that needs a connector says so in its requires field; see card-scheduled-script.md.

• A retired _config/connectors/<service>.secret.json file is read by nothing; bbx health flags any that survive. If you find one, report it for deletion — do not create new ones, and do not read one to "retrieve" a key.

gmail

Pulls mail through the Gmail API. Creates thread directories with message cards and body text files; sends the agent's email-outbound drafts.

Produces: email-thread, email-message (via the wakeup cycle)

google-drive

Two-way sync with Google Drive. Spreadsheets become .gsheet.card files with JSON tabs; Google Docs become .gdoc.card files with sibling markdown. Push detects conflicts when remote changed since the last pull.

The bbx drive verbs (inspect, mount, link, add, list) work from your shell even though you hold no Google credential: the server holds it and does that half for you. If Drive is not enabled, you may set googleServices.drive: true in _config/box.json when the boxholder asks for Drive. After mounting, run bbx force-wakeup --connector google-drive to confirm the first sync.

Produces: gdoc, gsheet, gfolder, glink (via the wakeup cycle)

google-calendar

Two-way sync between Google Calendar and .ics files in _content/calendar/. Viewing, creating, editing, and deleting events is the calendar skill (.claude/skills/calendar/); the file format, editability by calendar role, and filename form are the connector-calendar rule, which loads when an .ics file is in play. Sync state lives in _bookkeeping/connectors/.

Outbound only — no cards produced.