Unsendbox logo
Get started
← RETURN TO ROOT
Connected

Unsendbox Opencode setup

Turn this repo into an Opencode project with ChatGPT/Codex auth, MCP registrations, and local hooks.

Open Opencode guide

What gets added

Place these files under the repo root to standardize local AI operations.

opencode.json
Central project config for providers, MCP endpoints, hooks, and agents.
.opencode/plugins/unsendbox-guard.ts
Local command/tool guard that blocks risky shell actions and enforces consistency.
Docs link and templates
Operational documentation already exists under `/docs/user-guide/connect-ai-tool` and `/docs/user-guide`.

1) Add `opencode.json`

Use this baseline and keep secrets in environment variables.

  1. 01Copy the generated example into repo root as `opencode.json`.
  2. 02Set provider keys (`OPENAI_API_KEY`) and optional `UNSENDBOX_MCP_TOKEN` in environment.
  3. 03Set `UNSENDBOX_MCP_URL` to your target environment (`http://localhost:4100/api/v1/mcp` for dev).
  4. 04Set `UNSENDBOX_MCP_MODE` to your preferred default (`primary` for local-first flow).
  5. 05Enable the unsendbox MCP block and keep external MCP blocks disabled until needed.

2) MCP and org/API scope

Scope notes for production-safe usage.

MCP endpoint scope
Organization-scoped operations should be bound to your active Unsendbox workspace and member context.
API credentials
If using API-backed MCP fallbacks, rotate tokens in sync with org-level access changes.
Domain safety
Keep Google Workspace-first teams pointed at Workspace MX while routing only selected addresses via Unsendbox.

3) Install local guard plugin

Enable repo-level safety checks for Opencode commands.

  1. 01Keep local plugin file at `.opencode/plugins/unsendbox-guard.ts` from this template.
  2. 02Run initial session and verify pre-tool hooks are loaded before making file writes.
  3. 03Confirm destructive shell commands are blocked by default.
  4. 04Confirm one run of `list_threads` works, then `send_email` in a staging domain.

4) Skill-like agent model

Map repeated tasks to agent names and prompt framing.

unsendbox-operator
Primary runbook agent for onboarding, domain setup, and routine sending operations.
unsendbox-reviewer
Read-only verification agent for safety checks, suppression, and routing diagnostics.
default_agent
`unsendbox-operator` is used for most interactive tasks.

5) Verify configuration integrity

Run this checklist before handing the repo to the team.

  1. 01Start a fresh Opencode session from this repo.
  2. 02Run `/help` and verify `unsendbox` MCP tools are listed.
  3. 03Confirm `connect_domain`, `create_address`, `send_email`, and `get_domain_health` are callable.
  4. 04Check that `/docs/user-guide/connect-ai-tool` and `/docs/configuration/workspace-and-api-access` match runtime behavior.
  5. 05Document all env-var expectations in team onboarding notes.

Example config file

Keep this file as a reference and adjust IDs/URLs for your environment.

Start command
pnpm opencode start
Reference doc
Copy the sample from project notes if you need a fresh reset.
File location
/opencode.json

Helpful deep links

Use these pages to resolve setup and safety details.

Domain setup
/docs/domain-setup
Workspace and API access
/docs/configuration/workspace-and-api-access
Forwarding and hybrid routing
/docs/user-guide/forwarding-email

Rollback plan

If your Opencode session becomes unstable, revert safely.

  1. 01Rename `opencode.json` temporarily and restart Opencode.
  2. 02Disable local plugin loading and clear session cache if needed.
  3. 03Keep using dashboard operations while restoring MCP endpoint and auth tokens.
  4. 04Document any command policy changes before turning plugin hooks back on.
  5. 05Re-enable hooks only after two successful smoke tests.