Notion

Let your box read and write Notion pages through the host's authenticated ntn CLI — your token never enters the box

Give your box agent Notion access without putting your Notion token in the box. It can search your workspace, read pages, and query databases and data sources on its own — then create or update pages once you approve each write. Every call is proxied through the host's authenticated ntn CLI, the same model as agentbox-ctl git push.

HOW IT WORKS

The box runs a tiny ntn / notion shim. Calls go through agentbox-ctl integration notion <op> to the host relay, which runs the host's real ntn and ships the result back. Reads pass straight through. Writes raise a one-line confirm in your terminal first.

Prerequisites

The integration wraps Notion's official CLI (ntn — currently in beta). Install it on the host (not in the box):

# macOS / Linux — see the official docs for other install methods
brew install notion-cli
ntn login                # opens the browser, stores auth in the system keychain

Then verify with agentbox doctor:

integrations:
  [info] notion             disabled  (enable with `agentbox config set --project integrations.notion.enabled true`)

The integration is off by default, so even with ntn installed the box can't call it until you opt in. Doctor's info line confirms ntn is detected; flip the flag to graduate it to a usable state.

Enable it for this project

agentbox config set --project integrations.notion.enabled true

--project scopes it to the current project (config file under ~/.agentbox/projects/<hash>/). Drop --project for global. Run agentbox doctor again — the row should now read:

integrations:
  [ ok ] notion             ntn version X.Y.Z · authed

If you see [warn] not logged in, run ntn login on the host. If you see [warn] ntn not installed, the host install didn't put ntn on PATH.

What works inside the box

The in-box shim exposes a strict allowlist. Anything outside the list is rejected with a clear message — start conservative, widen as flows surface.

In-box command	Class	What happens
`ntn whoami`	read	Passes through; prints the authed host user.
`ntn api v1/<path>`	read	`GET` to any endpoint, plus the read-only POSTs `v1/search`, `v1/databases/<id>/query`, and `v1/data_sources/<id>/query` (pass the JSON body inline with `-d '<json>'`). Every other method/endpoint — writes like `v1/pages`/`v1/comments`, `-X PATCH`/`DELETE`, and the host-file `--input`/`--file` body sources — is refused with exit 65. Use `pages create`/`pages update` for writes.
`ntn pages create …`	write	Prompts the host for approval; on `y` the host runs `ntn pages create` and ships back the result.
`ntn pages update …`	write	Prompts the host for approval; covers props and archive.

notion is a symlink to ntn — either name works. Reads are unprompted; every write raises a one-line confirm in your attached terminal (or in agentbox agent approvals for orchestrators driving boxes headlessly — see Background & parallel).

# Inside the box — these all flow through the host relay:
ntn whoami
ntn api v1/pages/abc123                             # GET passthrough
ntn api v1/databases/def456                         # GET passthrough
ntn api v1/search -d '{"query":"roadmap"}'          # read-only POST
ntn api v1/data_sources/<id>/query -d '{}'          # read-only POST
ntn pages create -p <db-id> -t "Draft from the box" # prompts on the host

comment creation isn't supported yet

ntn has no top-level comment subcommand, and posting to v1/comments is a write — refused by the read-only api gate. There's no approved write op for comments yet, so the box can't create them.

Security model

Concern	What AgentBox does
Where the Notion token lives	Host only — in the macOS keychain (or `ntn`'s configured file-auth on Linux). The box has no access to either.
What the box can do unprompted	Reads only (`whoami`, `ntn api` GETs, and the read-only query/search POSTs).
What needs your approval	Every write (`page.create`, `page.update`). Any `api` call that isn't a read — a write method, or a POST to a non-read endpoint — is refused outright with exit 65.
Where the approval lives	The host relay raises a confirm prompt; you answer in the attached terminal (`y` / `n`) or via `agentbox agent approve <id>` from an orchestrator.
Inside the box, does the agent ever see the token?	No. `printenv \| grep -i notion` inside a box returns nothing — only `AGENTBOX_RELAY_TOKEN`, which only authenticates to the box-local relay endpoint.
Auditability	Every approved write is logged as a relay event (visible via `/admin/events`, `agentbox agent`, the dashboard).

The integration is off by default for every new project. You flip it on per project once you've installed and authed ntn on the host.

WHY this shape

The box is the untrusted side. Tokens in the box would survive agentbox download, leak into commits if the agent mishandles them, and undermine the entire sandbox premise. Keeping the token on the host and putting the gate at the host boundary is the same model AgentBox already uses for git push and gh pr create — one model, audited in one place.

Limitations and roadmap

Read-only api passthrough. ntn api allows GET to any endpoint and POST only to the read endpoints (v1/search, v1/databases/<id>/query, v1/data_sources/<id>/query). Every other method/endpoint — writes, PATCH/DELETE, host-file --file/--input bodies — is refused; use pages create/pages update for writes.
Comment creation isn't supported yet. No approved write op maps to v1/comments (see the callout above).
Allowlist starts conservative. As real agent flows surface needs, the op set will widen — file an issue with the failing call if something's missing.
Trello / ClickUp are still on the integrations roadmap; their connectors will appear in agentbox doctor the same way once they ship.

See also CLI commands for agentbox doctor, Configuration for the integrations.notion.enabled flag, and Background & parallel for the host-action approval surface.