Connect Coding Agents to Thegram with an API Key · r14

Archived revision r14, recorded 2026-10-16T01:26:30.010Z by portal-product-quickstarts. Current page: Connect Coding Agents to Thegram with an API Key.

Connect coding agents with an API key

Claude Code, Codex, OpenCode and OMP use the same coding plugin and Cloud MCP endpoint. No desktop app, DMG, Agent Access switch or local socket is required.

Prerequisites

Node.js 22+ on PATH and coding plugin 3.0.0 or later.
A Thegram account and explicit access to the intended Cloud vault or connected Drive account.
A person-issued API key with only the required resource scopes. Provider install and hook trust prompts remain the person’s decision.

Install the shared plugin

Run only the canonical block for the selected host. Each block installs the same public clab-one/thegram-mcp package; it does not create a separate desktop connection.

Claude Code:

claude mcp remove --scope user thegram >/dev/null 2>&1 || true
claude plugin marketplace add clab-one/thegram-mcp || claude plugin marketplace update thegram-memory
claude plugin install thegram-memory@thegram-memory
claude plugin update thegram-memory@thegram-memory || true

Codex:

codex mcp remove thegram >/dev/null 2>&1 || true
codex plugin remove thegram@thegram-local >/dev/null 2>&1 || true
codex features enable hooks
codex plugin marketplace add clab-one/thegram-mcp || codex plugin marketplace upgrade
codex plugin add thegram-memory@thegram-memory

OpenCode:

opencode plugin add github:clab-one/thegram-mcp

OMP:

omp plugin marketplace add clab-one/thegram-mcp || true
omp plugin install thegram-memory@thegram-memory
omp plugin upgrade thegram-memory || true

Issue and connect an API key

Sign in at https://vault.thegram.one/v3/ and open Settings → Agents → API keys.
Give the key a name, select only the required vaults and Drive accounts, choose read or write access where offered, and set an expiry no more than 90 days away.
Copy the one-time secret. Do not paste it into a chat, source file, command argument or shell history.
From the installed coding plugin directory, run the command below and enter the key at its hidden prompt. If more than one vault is authorized, follow the canonical guide to choose the exact mount.

node dist/thegram-memory.mjs connect
node dist/thegram-memory.mjs doctor

The CLI stores the connection privately; on POSIX the credential file is mode 0600. The saved key is bound to its endpoint. Start a new agent session after connecting. Connecting and doctor do not create a memory document.

Project memory and storage

All current agent connections use Thegram Cloud. Local-only files are not uploaded or exposed automatically. API keys authorize selected vaults and separately selected Drive accounts, intersected with current membership and organization policy. A vault grant is not a document-only sandbox.

Each repository uses its configured Cloud memory document, shared by worktrees. With write access the first agent session can initialize an empty project memory; read-only sessions do not create or modify it. Existing local-only memories require an explicit user-directed migration.

Verify without writing

gram_capabilities({})
gram_projects({})
gram_brief({ "folder": "<project folder or mount key returned by gram_projects>" })
gram_read({ "path": "<exact document path in gram_brief docs>" })
gram_read({ "path": "<same document path>", "section": "<heading returned by gram_read outline>" })

Expected: the selected authorized mount is visible. Read an existing document if one is listed; an empty vault is not a connection failure.

Troubleshooting

E_AUTH before any request: no local API key is configured. Run connect and enter a person-issued key privately; redeploying the UI does not enroll a local CLI.
HTTP 401: the key is invalid, expired or revoked. Issue a replacement in Settings and reconnect; do not reuse another person’s key.
E_FORBIDDEN or AGENT_SCOPE_DENIED: inspect the key scopes, vault role and organization policy. A key cannot widen them.
E_CONNECT or key_service_unavailable: check the configured endpoint and service readiness. Do not fall back to a desktop socket or a different storage location.
To revoke server access, delete the key in Settings. CLI disconnect only removes the local credential.

Optional first save and search

Keep installation and the checks above read-only. Save only after the person explicitly asks for this save, grants write access, approves the exact new path, and confirms that it does not already exist in that authorized folder. Never create a mount, overwrite a document, or use a write as a connection test.

Use the actual gram_create input shape; base_revision null creates a new document. Replace the path with a new path under the exact authorized project folder or mount, and use only text the person approved:

gram_create({
  "path": "<authorized-folder>/setup-notes.gram",
  "title": "Setup notes",
  "base_revision": null,
  "content": "# Setup notes"
})

Expected: the tool confirms the new document and returns its path/revision. Read it directly; search the same authorized folder with gram_recall when indexing is available:

gram_read({ "path": "<exact path returned by gram_create>" })
gram_recall({
  "query": "setup notes",
  "folder": "<same authorized folder or mount key>",
  "top_k": 5
})

Expected: gram_read returns the saved document; gram_recall returns matching indexed material or no result until indexing catches up. Both retrieval calls are read-only.

Canonical installation and mount selection: https://thegram.one/install/agents.md

Source and renderer evidence

Canonical source SHA-256: 66c7a825c24ce4cc25fac497fd4bf326e95e0771ae237ebf3b330dc7a713df11
Selected revision: r14 · sha256:8aa7b9b295477e5e1fc72f8cdc0e83550337d879f7b76ef89b8d7ef92abaca4c
Local renderer: configured local Thegram renderer · API thegram-web-render/1
Core source: git+https://github.com/clab-one/thegram-format.git?rev=b16489e1d0d77d38f82d2f61776524737aa31557#b16489e1d0d77d38f82d2f61776524737aa31557

Canonical source: 14.gram