Skip to main content
The Inkbox Codex plugin is a standalone bridge for Codex. It connects a Codex agent to an Inkbox identity and supports email, SMS/MMS and voice calls, iMessage, and an Inkbox tunnel when those channels are configured. This is a harness plugin, not an Inkbox SDK skill or marketplace bundle. It runs a persistent gateway that turns inbound messages and calls into real Codex sessions with access to the project directory you choose.

View plugin on GitHub

​
Prerequisites

  • Codex installed and logged in
  • Python 3.11 or newer
  • 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 agent-scoped API key.

​
Install

For sponsored group conversations, check the Companion receiver requirements before installing or updating. Run the one-command installer:
bash
The installer creates an isolated environment, adds inkbox-codex to your path, and launches the setup wizard. 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 Codex should work in
  • offers to keep the gateway running in the background and after restarts
Re-running the installer or inkbox-codex setup is safe when you need to change the configuration.

​
Run the gateway

Check the configuration, then start the gateway if the setup wizard did not already start it:
bash
Use these commands to manage it later:
bash
Keep the gateway running. On startup it opens an Inkbox tunnel, configures the identity’s inbound channels, and routes configured email, SMS/MMS, iMessage, and call channels into Codex sessions.

​
Companion mode

The Companion contract requires SDK 0.7.3 or later. Confirm your installed Codex adapter supports the current receiver contract. Updating only the SDK does not establish plugin compatibility. Enable the separate Companion toggle, then use active exact bidirectional allows to make senders eligible. The preference can be saved before rules or resources exist. A qualifying authenticated group message activates the scope. The gateway must load the complete snapshot into one combined Codex input, hold later live messages, and checkpoint the initialization turn. Replies and sponsor-specific approvals must remain bound to the original activation and actual trigger author. Historical text is not a fresh approval response; existing host restrictions still apply. Installing or updating does not enable Companion mode. Restart the gateway after upgrading. See Companion mode for channel requirements, size failures, and revocation.

​
Available capabilities

Depending on your setup choices and account availability, your Codex agent can have:
  • An email address - send, receive, and reply from an Inkbox mailbox
  • A phone number, when available - SMS/MMS and voice calls, inbound and outbound
  • iMessage, when connected - continue the same agent conversation from an iMessage thread
  • An Inkbox tunnel - inbound messages and calls reach the local gateway without a public server
  • Persistent Codex sessions - each contact keeps one conversation across configured email, text, iMessage, and call channels
  • Remote permission prompts - approve or reject Codex tool requests from the channel you are using
Codex also receives Inkbox tools for sending messages, placing calls, reading conversation history, managing contacts, and delegating work to other agents.

​
What Inkbox adds

Codex itself stays upstream. The plugin adds the Inkbox identity, gateway, channel routing, session continuity, messaging tools, and setup commands without requiring a Codex fork.

​
Permission prompts

When Codex wants to run a command, change files, change its permission profile, or ask you a question, the plugin pauses the request and sends you a short prompt. Reply to allow it once, allow that kind of action for the current session, or reject it. Questions from Codex are delivered as numbered choices. Your next reply answers the pending question instead of starting a separate turn.

​
After install

Run a health check:
bash
Use any channels you configured. If the agent has a phone number, text START to it from every phone the agent needs to text. You can also email the agent mailbox, connect over iMessage when enabled, or call the agent phone number when available. The gateway routes each configured channel into Codex and returns the response on the channel you most recently used.