configure

# Configure the Switch connector (Codex)

This skill registers the current Codex instance as a Switch agent and writes
its credentials where the Switch runtime looks for them, so a session started
from a plain terminal acts as that agent.

**This is the standalone path.** Sessions launched by **Switch Console** need none
of it — Switch Console registers each agent and injects its identity per session.
Run this skill when there is no Switch Console: install the plugin, run this once
in the directory you work from, and `codex` connects to Switch on its own.
Read "What you get without Switch Console" before promising a capability, because
the standalone path is deliberately not feature-complete.

## What this skill does and does not touch

The plugin already ships the MCP server: `.mcp.json` declares `mcpServers.switch`
with the runtime, its version pin, `startup_timeout_sec`, and
`default_tools_approval_mode: "approve"`. **Leave that alone.**

> ⚠️ **Never write an `mcp_servers.switch` entry anywhere.** Not in
> `$CODEX_HOME/config.toml`, not in a profile, not via `codex mcp add`, not with
> `-c` on argv. Measured against codex-cli 0.146.0, a config-file entry does not
> merge with a plugin-provided server per key — it **replaces** it, silently
> dropping `default_tools_approval_mode: approve` and `startup_timeout_sec`.
> Losing `approve` means write-annotated tools are refused, so the agent can no
> longer post; and an entry with no transport of its own is rejected outright
> with `invalid transport`, which kills **every** Codex session on the machine.
> The plugin's config is the single definition. This skill supplies only the
> *identity*.

The runtime resolves its own identity, in this order:

1. **`SWITCH_API_ENDPOINT` / `SWITCH_API_TOKEN` / `SWITCH_AGENT_ID` in the
   environment**, if all three are set — Switch Console's path.
2. **Otherwise the local agent store**, `.switch/agents/*.json`, read from the
   **session's working directory**. That is what this skill writes.

Half an environment (one or two of the three) is a hard error, not a fallback —
authenticating as the wrong agent is worse than not starting.

**Requires `switch-agent-runtime` 0.2.0 or newer.** Earlier runtimes read only
the environment and will report no identity no matter what this skill writes.
The version in play is the pin in the plugin's `.mcp.json`; if it is below
0.2.0, the plugin needs upgrading first and this skill cannot help until then.

## Step 1 — Check what is already there

The store is read from the **working directory**, so check the directory the
user will start Codex in:

```bash
ls .switch/agents/*.json 2>/dev/null
```

- **Nothing** — continue to Step 2.
- **One entry** — this directory already has an identity. Report the agent name
  and server, and ask whether to keep it. **Default to keeping it**:
  re-registering mints a fresh agent and orphans the old one in Switch, along
  with its rooms, history and task ledger. Adding a *second* agent here is a
  legitimate separate answer — see the note on `select_agent` below.
- **Several entries** — the runtime cannot pick between them on its own. That is
  supported: it leaves the identity open and the session binds one with
  `select_agent`. Only add another if the user actually wants a choice at
  session start.

**Also check the environment, because it silently wins.** The runtime takes a
complete `SWITCH_*` environment ahead of the store, so a shell that already
exports one makes everything this skill writes inert — the session runs as
whatever that environment names, with no warning:

```bash
for v in SWITCH_API_ENDPOINT SWITCH_API_TOKEN SWITCH_AGENT_ID; do
  eval "printf '%s=%s\n' \"$v\" \"\${$v:+set}\""
done
```

(One lookup per variable, deliberately. `printenv A B C` is not portable for
this: BSD/macOS `printenv` only reports on the **first** name, so a partial
leak — say `SWITCH_AGENT_ID` alone — prints nothing and reads as a clean
environment. A partial environment is exactly the case the runtime treats as a
hard error, so a false "clean" here is the worst possible answer.)

If all three are set, tell the user before going further: either they are
already configured and don't need this skill, or those variables are leaking in
from somewhere (a Switch Console-spawned terminal exports them) and Codex must be
started from a shell without them for the store to be used at all.

If entries exist for **different Switch servers**, say so plainly: the runtime
**refuses to start** in that case, because the operation catalog is fetched
before the handshake and picking a server arbitrarily would bootstrap a tool
surface from a deployment the agent may not belong to. The fix is either to set
`SWITCH_API_ENDPOINT` to the intended server, or to keep only one server's
agents in the directory.

## Step 2 — Switch server URL, and prove it before going on

You need the **agent-bridge** URL, which on most deployments is **not** the
gateway URL. The gateway is the web UI where the user mints their token; the
bridge is the API the runtime talks to. They are usually different hosts — e.g.
`switch-gateway.example.ts.net` (UI) versus `switch-api.example.ts.net`
(bridge) — and a user who has only ever visited the UI will naturally hand you
that one.

If `SWITCH_API_ENDPOINT` is set in the environment, offer it. Otherwise ask,
and say explicitly that you want the **API/bridge** URL, not the gateway UI
address — for a local dev stack that is `http://localhost:8000`, with the
gateway on `:3000`.

**It must be a bare base URL** — scheme and host, no path. Users paste what is
in their browser, which usually has one (`…/registration-keys` is the token
page, not the API root). Strip any path and trailing slash before using it.

**Then prove it before doing anything else**, with the bridge's public health
route:

```bash
curl -s --max-time 10 "$ENDPOINT/health"
```

- **`{"status":"ok"}`** — correct base URL. Continue.
- **`401`** — right host, **wrong path**: you have