Bee Box documentation · directory: https://beebox.run/docs/reference/ · index: https://beebox.run/docs/reference/index.md · root: https://beebox.run/llms.txt

# 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. They live in one machine-level store outside every
box's directory, and this box holds a *grant* to the ones the boxholder decided it may use.
You cannot read that store, add to it, or grant anything — those are the boxholder's
decisions, made from the admin page or the `bbx secrets` CLI. Google services are separate
again: shared OAuth tokens plus the box's `googleServices` policy in `_config/box.json`.

Rules for handling keys:

- **Never write a key into this box.** Not a card, not CLAUDE.md, not a config or `.env`
  file, not a script, not a log line, not a chat message. There is exactly one copy of each
  key and rotation is supposed to touch only that copy. A key in the tree also gets pushed
  to the box's git remote.
- **To get a key configured**, ask the boxholder to add and grant it — they can do it from
  the admin page's Secrets section. Say which name you need and what for; do not offer to
  save it for them, and never accept one pasted into chat.
- **To USE a key from code you write** (a trick, a scheduled script, a procedure step),
  resolve it by name at call time over the loopback API — see the agent guide's secrets
  section for the exact request. It needs a grant at `agent` access. Hold the value in a
  local variable for the length of the outbound call and never store it anywhere.
- Built-in connectors (Telegram, Gmail, transcription, …) resolve their own credentials
  inside the server process. You never see or need those values.
- A scheduled script can declare `<requires><connector>name</connector></requires>`; the
  scheduler checks whether the box has a granted credential for that connector and skips
  the script cleanly when it doesn't.
- 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 emails from Gmail via IMAP. Creates thread directories with message cards and body text files.

**Produces:** `email-thread`, `email-message` (via `bbx wakeup`)

## 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.

**Produces:** `gsheet`, `gdoc` (via `bbx wakeup`)