Skip to main content
The Inkbox OpenCode plugin (@inkbox/opencode-plugin) is a standalone plugin for OpenCode. It connects an OpenCode agent to an Inkbox identity and exposes configured email, SMS/MMS, voice-call, iMessage, contact, note, and encrypted-vault capabilities as native OpenCode tools. This is a plugin, not an Inkbox SDK skill or an OpenCode fork. It ships as source you build locally and loads through OpenCode’s plugin system, with an optional gateway that turns configured inbound email, SMS/MMS, iMessage, and calls into OpenCode sessions.

View plugin on GitHub

​
Prerequisites

  • OpenCode installed and logged in to a model provider
  • Node.js 20 or newer and Git
  • macOS or Linux
You do not need to create an Inkbox identity first. The setup wizard can sign up a new agent or connect an existing API key.

​
Install

For sponsored group conversations, check the Companion receiver requirements before installing or updating. The fastest path is the one-command installer. It builds the plugin from source, wires it into your global OpenCode config, and runs the setup wizard:
bash
The wizard creates or connects an Inkbox agent, offers to provision a phone number, offers to connect iMessage, configures signed inbound messaging, asks which project directory OpenCode should use, and offers to keep the gateway running in the background and after restarts. Re-running the installer or inkbox-opencode setup is safe. Check the wiring anytime with inkbox-opencode doctor.

​
Manual install

To install per-project or without the installer, clone and build the plugin:
bash
From your OpenCode project, install the packed build and add a wrapper that OpenCode auto-loads from .opencode/plugins/:
bash
Create .opencode/plugins/inkbox.ts. All plugin options — tool gating, the recipient allowlist, the gateway — go inside the InkboxPlugin(input, { ... }) call here:
TypeScript
Provide credentials with environment variables (they also fall back to ~/.inkbox/config). Get both from the Inkbox Console:
bash
Then point OpenCode at the bundled skills so the agent knows Inkbox etiquette, and ask it to run inkbox_doctor to confirm the setup:
JSON

​
Companion mode

The Companion contract requires SDK 0.7.3 or later. Confirm your installed OpenCode adapter supports the current receiver contract. Updating the SDK alone does not establish plugin compatibility. Enable the separate Companion toggle, then use active exact bidirectional allows to make senders eligible. You can save the preference before rules or resources exist. The gateway must load the full authorized snapshot into one combined OpenCode input, checkpoint the activation, and hold later live messages. Replies retain the original activation’s exact email audience or canonical text/iMessage conversation ID. Historical content must not answer current approvals or run as commands. Existing host restrictions still apply; incomplete context or uncertain acceptance must not release partial initialization. Installing or updating does not enable Companion mode. Rebuild and restart the gateway after upgrading. See Companion mode for channel requirements and revocation.

​
Available capabilities

Depending on your setup choices, enabled tools, and account availability, your OpenCode agent can have:
  • An email address - send, receive, and reply from an Inkbox mailbox
  • A phone number, when available - SMS/MMS, call history and transcripts, and outbound calling when the call tool is enabled
  • iMessage, when connected - each person who messages the agent gets their own ongoing thread to reply on
  • Contacts and notes - persistent Inkbox records the agent can create and read
  • An encrypted vault - opt-in credential storage whose plaintext tools require explicit enablement and an unlock key
  • An inbound gateway - configured email, SMS/MMS, iMessage, and calls can open OpenCode sessions that reply on the same channel
Outbound email, SMS, iMessage, and calls request approval through OpenCode’s native permission prompts, or you can set a recipient allowlist in the wrapper.

​
What Inkbox adds

OpenCode itself stays upstream. The plugin registers Inkbox tools, routes outbound sends through OpenCode’s permission prompts, bundles task skills, and can run an inbound gateway, without requiring an OpenCode fork.

​
Inbound gateway

The plugin can run a long-lived inbound gateway that receives email, SMS/MMS, iMessage, and calls to the agent’s identity and turns each into an OpenCode session that replies on the same channel. The setup wizard configures and offers to start the sidecar. For a manual install, enable it with gateway: { enabled: true, projectDirectory } in the wrapper and set a webhook signing key (INKBOX_SIGNING_KEY). The sidecar finds or launches its own OpenCode server:
bash

​
After install

Use any channels you configured. If the agent has a phone number, text START to it from every phone the agent needs to text. This opts that phone number in to SMS from the agent. You can also email the agent mailbox, use iMessage when connected, or call the agent phone number when available.