Codex App-Server Runtime (optional)

​

Why

• Run OpenAI agent turns against your ChatGPT subscription (no API key required) using the same auth flow Codex CLI uses.
• Use Codex’s own toolset and sandbox — shell for terminal/read/write/search, apply_patch for structured edits, update_plan for planning, all running inside seatbelt/landlock sandboxing.
• Native Codex plugins — Linear, GitHub, Gmail, Calendar, Canva, etc. — installed via codex plugin are auto-migrated and active in your Mibyan session.
• Mibyan’ richer tools come along — web_search, web_extract, browser automation, vision, image generation, skills, and TTS work via an MCP callback. Codex calls back into Mibyan for tools it doesn’t have built in.
• Memory and skill nudges keep working — Codex’s events are projected into Mibyan’ message shape so the self-improvement loop sees a normal-looking transcript.
• Your Mibyan persona rides along — the composed system prompt (SOUL.md, MEMORY.md/USER.md, per-channel system_prompt overrides) is sent to the codex thread once as developer instructions when the thread starts, and Codex’s built-in personality is disabled so it cannot compete with yours.

​

What tools the model actually has

​

1. Codex’s built-in toolset (always on)

• shell — runs arbitrary shell commands inside the sandbox. This is how the model reads files (cat, head, tail), writes them (echo > foo, heredocs), searches them (find, rg, grep), navigates directories (ls, cd), runs builds, manages processes, and anything else you’d do in bash.
• apply_patch — applies a structured multi-file diff in Codex’s patch format. The model uses this for non-trivial code edits (adding a function, refactoring across files); shell heredocs are still available for one-off writes.
• update_plan — codex’s internal todo / plan tracker. Equivalent of Mibyan’ todo tool, but managed entirely inside codex’s runtime.
• view_image — load a local image file into the conversation so the model can see it.
• web_search — codex has its own built-in web search when configured. Mibyan also exposes web_search (Firecrawl-backed) via the callback below; the model picks whichever it prefers.

​

2. Native Codex plugins (auto-migrated from your codex plugin install)

• Linear — find/update issues
• GitHub — search code, view PRs, comment
• Gmail — read/send mail
• Google Calendar — create/find events
• Outlook calendar/email — same shape via the Microsoft connector
• Canva — design generation
• …whatever else you’ve installed via codex plugin marketplace add openai-curated + codex plugin install ...

• Plugins you haven’t installed yet — install them in Codex first.
• ChatGPT app marketplace entries (app/list) — these are already enabled inside codex by virtue of your account auth.

​

3. Mibyan tool callback (MCP server, registered in ~/.codex/config.toml)

• web_search / web_extract — Firecrawl-backed; tends to be cleaner than scraping for structured content.
• browser_navigate / browser_click / browser_type / browser_press / browser_snapshot / browser_scroll / browser_back / browser_get_images / browser_console / browser_vision — full browser automation via Camofox or Browserbase.
• vision_analyze — call a separate vision model to inspect an image (different from codex’s view_image which loads it into the conversation).
• image_generate — image generation through Mibyan’ image_gen plugin chain.
• skill_view / skills_list — read from Mibyan’ skill library.
• text_to_speech — TTS through Mibyan’ configured provider.

​

What’s NOT available on this runtime

• delegate_task — spawn subagents
• memory — Mibyan’ persistent memory store
• session_search — cross-session search
• todo — Mibyan’ todo store (codex’s update_plan is the in-runtime equivalent)

​

Workflow features (/goal, kanban, cron)

​

/goal (the Ralph loop)

​

Kanban (multi-agent worktree dispatch)

• Codex’s full toolset (shell, apply_patch, update_plan, view_image, web_search) — the worker does its actual task work natively
• The migrated codex plugins — Linear, GitHub, etc.
• The Mibyan tool callback for browser_*, vision, image_gen, skills, TTS

• kanban_complete / kanban_request_review / kanban_request_changes / kanban_block / kanban_comment / kanban_heartbeat — the worker handoff tools. These read mibyan_KANBAN_TASK from env (set by the dispatcher), gate access correctly, and write to the per-board SQLite DB pinned by mibyan_KANBAN_DB. Without these in the callback, a worker on this runtime could do its task but couldn’t report back, hanging until the dispatcher’s timeout.
• kanban_show / kanban_list — read-only board queries for the worker to check its own context.
• kanban_create / kanban_unblock / kanban_link — orchestrator-only operations. Available for orchestrator agents running on the codex runtime that need to dispatch new tasks.

​

Cron jobs

​

Trade-offs

​

Live display

• Live assistant deltas, reasoning (including summary deltas), and stable-ID tool start/completion events surface in the TUI, desktop, and messaging gateways as the turn runs. The completion-only history projector remains separate, so a resumed session hydrates the same tool cards shown during the turn.
• Gateway commentary stays visible when token streaming is disabled, and live tool events are forwarded even for notifications drained ahead of an approval request. Commentary honors display.show_commentary.

​

Prerequisites

1. Codex CLI installed:
   npm i -g @openai/codex
   codex --version   # 0.130.0 or newer
   
2. Codex OAuth login. The codex subprocess reads ~/.codex/auth.json. Two ways to populate it:
   codex login                  # writes tokens to ~/.codex/auth.json
   
   Mibyan’ own mibyan auth add openai-codex writes to ~/.mibyan/auth.json — that’s a separate session. Run codex login separately if you haven’t. Or: a named custom provider. A providers.<name> entry in Mibyan config can use this runtime when the same name is defined as a Codex provider. Mibyan config:
   providers:
     my-gateway:
       api: https://gateway.example.com/v1
       key_env: MY_GATEWAY_API_KEY
       default_model: gpt-5.4
   
   model:
     provider: custom:my-gateway
     default: gpt-5.4
     openai_runtime: codex_app_server
   
   and the matching table in ~/.codex/config.toml:
   [model_providers.my-gateway]
   name = "My Gateway"
   base_url = "https://gateway.example.com/v1"
   env_key = "MY_GATEWAY_API_KEY"
   wire_api = "responses"
   
   Mibyan sends only model and modelProvider = "my-gateway" on thread/start; codex resolves base_url and reads the key from env_key in its own environment. Mibyan never forwards the API key, so MY_GATEWAY_API_KEY must be present in the process environment Mibyan runs in — ~/.mibyan/.env is loaded at startup and provider credentials are inherited by the codex subprocess. Auxiliary calls (titles, compression, memory review) still use Mibyan’ own providers.my-gateway entry. Caveats: the name after custom: is the providers: config key and must match the [model_providers.<name>] table name exactly — if it does not exist on the codex side, codex reports an unknown provider rather than silently using the Mibyan endpoint. Anonymous provider: custom (a bare base_url) is not eligible: it has no stable name to hand to codex, so it stays on Mibyan’ standard runtime.
3. (Optional) Install the Codex plugins you want. When you enable the runtime, Mibyan auto-migrates whichever curated plugins you’ve already installed via Codex CLI:
   codex plugin marketplace add openai-curated
   # then via codex's TUI, install Linear / GitHub / Gmail / etc.
   
   Mibyan will discover them and write [plugins."<name>@openai-curated"] entries to ~/.codex/config.toml automatically.

​

Enabling

/codex-runtime codex_app_server

• Verifies the codex CLI is installed (blocks with an install hint if not).
• Persists model.openai_runtime: codex_app_server to your config.yaml.
• Migrates user MCP servers from ~/.mibyan/config.yaml to ~/.codex/config.toml.
• Discovers and migrates installed native Codex plugins (Linear, GitHub, Gmail, Calendar, Canva, etc.) by querying Codex’s plugin/list RPC.
• Registers Mibyan’ own tools as an MCP server so the codex subprocess can call back for tools codex doesn’t ship with.
• Writes default_permissions = ":workspace" so the sandbox allows writes within the workspace without prompting for every operation.
• Tells you what was migrated. Takes effect on the next session — the current cached agent keeps the prior runtime so prompt caches stay valid.

/codex-runtime

model:
  openai_runtime: codex_app_server   # default is "auto" (= Mibyan runtime)

model:
  openai_runtime: codex_app_server
  codex_bin: /Applications/Codex.app/Contents/Resources/codex   # default: "codex" from PATH

​

Self-improvement loop (memory + skill nudges)

• Every 10 user prompts → a forked review agent looks at the conversation and decides whether anything should be saved to memory.
• Every 10 tool iterations within a single turn → same idea but for skills (skill_manage writes).

​

How approvals work

╭───────────────────────────────────────╮
│ Dangerous Command                     │
│                                       │
│ /bin/bash -lc 'echo hello > foo.txt'  │
│                                       │
│ ❯ 1. Allow once                       │
│   2. Allow for this session           │
│   3. Deny                             │
│                                       │
│ Codex requests exec in /your/cwd      │
╰───────────────────────────────────────╯

• Allow once → approve this single command.
• Allow for this session → Codex won’t re-prompt for similar commands.
• Deny → command is rejected; Codex continues in read-only mode.

​

Permission profiles

• :read-only — no writes; every shell command requires approval
• :workspace — writes within the current workspace allowed without prompts (Mibyan’ default when you enable the runtime)
• :danger-no-sandbox — no sandbox at all (don’t use this unless you understand it)

default_permissions = ":read-only"

​

Auxiliary tasks and ChatGPT subscription token cost

auxiliary:
  title_generation:
    provider: openrouter
    model: google/gemini-3-flash-preview
  compression:
    provider: openrouter
    model: google/gemini-3-flash-preview
  vision:
    provider: openrouter
    model: google/gemini-3-flash-preview
  goal_judge:
    provider: openrouter
    model: google/gemini-3-flash-preview

​

Editing ~/.codex/config.toml safely

# managed by mibyan-agent — `mibyan codex-runtime migrate` regenerates this section
default_permissions = ":workspace"
[mcp_servers.filesystem]
...
[plugins."github@openai-curated"]
...
# end mibyan-agent managed section

• Add your own MCP servers Mibyan doesn’t know about
• Override default_permissions to :read-only if you prefer to be prompted
• Configure codex-only options (model, providers, otel, etc.)
• Add user-defined permission profiles in [permissions.<name>] tables

​

Running the migration from a script

mibyan codex-runtime migrate            # rewrite the managed block for the active profile
mibyan codex-runtime migrate --dry-run  # report only, no write
mibyan codex-runtime migrate --json     # machine-readable report (migrated, preserved_user_servers, errors, …)
mibyan -p work codex-runtime migrate    # a named profile's mcp_servers

​

Multi-profile / multi-tenant setups

# Inside the work profile, you might wrap mibyan:
CODEX_HOME=~/.mibyan/profiles/work/codex mibyan chat

​

HOME environment variable passthrough

• Commands codex runs via its shell tool see the real user HOME and find ~/.gitconfig, ~/.gh/, ~/.aws/, ~/.npmrc, etc. correctly.
• Codex’s internal state stays isolated through CODEX_HOME (which points at ~/.codex/ by default).

​

MCP server migration

• Mibyan-specific keys like sampling (Codex’s MCP client has no equivalent — these are dropped with a per-server warning).

​

Native Codex plugin migration

• Plugins you haven’t installed yet — install them in Codex first.
• Plugins where codex reports availability != AVAILABLE (broken install, expired OAuth, removed from marketplace, etc.). These are skipped to avoid writing config that would fail at activation time.
• ChatGPT app marketplace entries (the per-account app/list results — these are already enabled inside codex by virtue of your account auth).
• Plugin OAuth — you authorize each plugin once in Codex itself; Mibyan doesn’t touch credentials.

​

Mibyan tool callback (the new MCP server)

[mcp_servers.mibyan-tools]
command = "/path/to/python"
args = ["-m", "agent.transports.mibyan_tools_mcp_server"]
env = { mibyan_HOME = "/your/.mibyan", PYTHONPATH = "...", mibyan_QUIET = "1" }
startup_timeout_sec = 30.0
tool_timeout_sec = 600.0

​

Disabling

/codex-runtime auto

​

Limitations

• Multi-turn conversations
• commandExecution and fileChange (apply_patch) approvals via Mibyan UI
• MCP tool calls (verified against @modelcontextprotocol/server-filesystem and the new mibyan-tools callback)
• Native Codex plugin migration (verified against Linear / GitHub / Calendar inventory)
• Deny/cancel paths
• Toggle on/off cycle
• Memory and skill nudge counters (verified live via integration tests)
• Mibyan web_search through codex (verified live: “OpenAI Codex CLI – Getting Started” returned end-to-end)

• Mibyan auth and codex auth are separate sessions. You need both codex login AND mibyan auth add openai-codex for the cleanest UX (the runtime uses codex’s session for the LLM call). This is a deliberate design choice in Mibyan’ _import_codex_cli_tokens — Mibyan won’t share OAuth state with codex CLI to avoid clobbering each other on token refresh.
• delegate_task, memory, session_search, todo are unavailable on this runtime. They need the running AIAgent context which a stateless MCP callback can’t provide. Use /codex-runtime auto when you need these.
• No inline patch preview in approval prompts when codex doesn’t track the changeset. Codex’s fileChange approval params don’t always carry the changeset. Mibyan caches the data from the corresponding item/started notification when possible, but if approval arrives before the item has streamed, the prompt falls back to whatever reason codex provides.
• fallback_providers fail over only on quota and rate-limit failures. When a codex app-server turn fails with a billing / usage-limit / rate-limit error, Mibyan switches to the configured fallback provider and retries the same turn on it; auth failures (codex login expired), turn timeouts and unknown-model errors do not fail over on this runtime and surface as the turn’s error instead.
• Prior Mibyan history is seeded only into a thread codex starts from scratch. A codex thread that codex hands back via thread/resume already holds the conversation. When no resumable thread exists — the session ran on another provider before /model switched to openai-codex, codex could not resume the stored thread, or the running thread was retired — the new thread’s developerInstructions carry Mibyan’ system prompt followed by the session’s prior turns (user and assistant text, tool names, tool-result previews; the most recent ~32K characters). When the composed prompt changes mid-session (for example /personality in the TUI or Desktop), the next turn retires the running thread and starts a new one carrying the updated prompt plus that same history seed.
• The codex thread itself does survive a restart. After each committed turn Mibyan stores the codex thread id on the session row (codex_thread_id in the session’s model_config, mibyan sessions / state.db). The next agent built for that same Mibyan session — a later /api/sessions/{id}/chat request, or the first turn after the API server or gateway restarts — issues thread/resume for the stored id before turn/start, so the model keeps its own memory of the earlier turns (that is why no history seed is sent on resume). When codex cannot hand the thread back (its rollout was deleted, CODEX_HOME changed, the previous app-server was killed while still writing it), Mibyan fails closed: it drops the stored id, starts a fresh thread and shows one line — Codex thread could not be resumed; starting a new one. — on the status rail of the surface you are on (CLI, TUI/Desktop, messaging gateway). A /new session never resumes an older thread.
• Sub-second cancellation isn’t guaranteed. Mid-stream interrupts (Ctrl+C while codex is responding) are sent via turn/interrupt, but if codex has already flushed the final message, you get the response anyway.

​

Architecture

                ┌─── Mibyan shell (CLI / TUI / gateway) ───┐
                │  sessions DB · slash commands · memory   │
                │  & skill review · cron · session pickers │
                └──┬──────────────────────────────────────┬┘
                   │ user_message               final     │
                   ▼                            text +    │
        ┌──────────────────────────────────┐   projected  │
        │  AIAgent.run_conversation()       │   messages   │
        │   if api_mode == codex_app_server │              │
        │     → CodexAppServerSession       │              │
        │   else: chat_completions / codex_responses (default)
        └────┬─────────────────────────────┘              │
             │ JSON-RPC over stdio                        │
             ▼                                            │
        ┌──────────────────────────────────┐              │
        │  codex app-server (subprocess)    │──────────────┘
        │   thread/start|resume, turn/start │
        │   item/* notifications            │
        │   shell + apply_patch + update_plan│
        │   view_image + sandbox            │
        │   ┌─────────────────────────┐     │
        │   │  MCP client             │     │
        │   │  ├─ user MCP servers    │     │
        │   │  ├─ native plugins      │     │
        │   │  │   (linear, github,   │     │
        │   │  │    gmail, calendar,  │     │
        │   │  │    canva, ...)       │     │
        │   │  └─ mibyan-tools ───────┼─────────────────┐
        │   │       (callback to     │     │           │
        │   │        Mibyan' richer  │     │           │
        │   │        tools)          │     │           │
        │   └─────────────────────────┘     │           │
        └──────────────────────────────────┘           │
                                                        │
                                                        ▼
        ┌──────────────────────────────────────────────────────────┐
        │  mibyan_tools_mcp_server.py (subprocess on demand)        │
        │   web_search, web_extract, browser_*, vision_analyze,    │
        │   image_generate, skill_view, skills_list, text_to_speech│
        └──────────────────────────────────────────────────────────┘