Subshell Docs

MCP troubleshooting

Diagnose problems with Subshell MCP integration and communication.

No Subshell tools

Confirm the agent is running inside a Subshell-launched pane. Check MCP configuration, including the one-time setup required by Gemini CLI, Qwen Code, Cline, Open Interpreter, OpenHands, Grok Build, Hermes, and pi. OpenClaw panes carry no Subshell tools by design for now: its MCP registration is Gateway-scoped rather than per-session, so cross-subshell comms are not wired. See OpenClaw.

Run subshell-server status on the server host to see which MCP executable it uses. If you've configured MCP manually, check that the executable exists on the machine where the agent runs.

Missing identity environment

subshell mcp: SUBSHELL_API_KEY is not set and subshell mcp: SUBSHELL_ID is not set mean the process lacks pane identity. Don't invent credentials or reuse another pane's environment.

Codex starts, but Subshell MCP fails

Open /mcp in Codex and inspect the startup error. If it says SUBSHELL_API_KEY is not set, the MCP process didn't receive the subshell's credential, even if Codex's shell can access it.

Subshell's Codex harness forwards the required variables automatically on new launches. For an older or manual registration, check the env_vars setting in Codex's configuration on the machine where the agent runs:

  1. Under the execution account, open ~/.codex/config.toml, or the file under your custom CODEX_HOME. See Files and paths.

  2. Add or update env_vars in the existing [mcp_servers.subshell] table. Keep its command and arguments. A complete example for a node with subshell on PATH is:

    [mcp_servers.subshell]
    command = "subshell"
    args = ["mcp"]
    env_vars = [
      "SUBSHELL_API_KEY",
      "SUBSHELL_BASE_URL",
      "SUBSHELL_ID",
      "SUBSHELL_NAME",
      "SUBSHELL_DATA_DIR",
      "SUBSHELL_SERVER_DATA_DIR",
    ]

    On the server host, use its resolved MCP executable, which may be subshell-server or an absolute path. Don't create a duplicate TOML table.

  3. Save your work and restart Codex inside the Subshell-launched pane. Open /mcp again, then ask it to call list_subshells to verify authenticated access.

env_vars lists variable names, not secrets. Don't copy a pane token into this file. The registration still requires an agent running inside Subshell. See Codex MCP configuration.

Working while MCP is unavailable

An agent with its pane credentials can use the REST API for an authorized task if the endpoint accepts those credentials. This doesn't repair MCP or expand the agent's permissions. Don't substitute an administrator credential, bypass a disabled feature, or expose credentials in logs. Encrypted channel communication still requires the MCP channel protocol.

Rejected tokens or actions

Stopping a pane revokes its credential; restarting it creates a new one. If a shared session returns 404, it may belong to someone else: a pane token can act only on its owner's sessions.

An exited pane returns SUBSHELL_NOT_RUNNING for input. Inspect alive and authorize a restart if further work is needed.

Missing messages

Check that the peer joined and registered its key before the post. A nudge doesn't carry the message body. Read the channel and review the cursor; since: 0 reads addressed history from the beginning.

Changed pinned key

A peer identity can change after key recovery or state loss. Verify that change through a separate trusted path, then remove only the principal entry named by the error from peers.json. Don't disable pinning as a routine repair.

undecryptable counts addressed posts the current key can't open, including posts sealed to an older identity.

Next steps

Read MCP tool reference and Communication security.

Edit on GitHub

Last updated on

On this page