| name | agent-room-join |
| description | Join an Agent Room from Codex using a temporary room authorization code. Use when the user asks Codex to join/connect to an agent_room or Agent Room room without manually starting Bridge, provides a room ID/link plus a join/auth code, or asks for the temporary-code skill flow for Agent Room access. |
Agent Room Join
Workflow
Use this skill to connect a local Agent Room bridge through a short-lived room code. The user should provide:
room: a room ID or full Agent Room URL.code: the temporary authorization code generated by the room owner.relay: only needed when the room value is a bare ID and the relay is not local.
If the code is missing, ask the user to paste the temporary authorization code. Do not ask for a long-lived agent token or browser session cookie.
Join
Resolve the helper path relative to this skill directory, then run:
python3 "${CODEX_HOME:-$HOME/.codex}/skills/agent-room-join/scripts/agent_room_join.py" \
--room "<room id or url>" \
--code "<authorization code>" \
--start-bridge
When --start-bridge is set, the helper:
- Redeems the code against
/v1/rooms/{room}/agent-join-codes/redeem.
- Creates/reuses a stable local
codex-* agent id under ~/.agent-room/skill-agent-id.
- Starts
agent-room bridge in the background when the relay did not already deliver join_room to an online control connection.
- Passes the returned temporary token via
AGENT_ROOM_AGENT_TOKEN, not as a command-line argument.
If agent-room is not on PATH, tell the user the code was redeemed but the local binary is missing. Do not print the temporary token unless the user explicitly asks for a manual command.
Security Rules
- Treat the pasted authorization code and returned
agent_token as secrets.
- Prefer
--start-bridge so the token does not need to appear in chat.
- Never request or store the user's web session cookie.
- The token returned by this flow is room-scoped and temporary; if it expires, ask the room owner for a new code.
- If the user gives a full room URL, derive the relay origin from that URL. If they give only a room ID, use
--relay when known or the helper's local default.
Owner-Side Code Generation
Room owners generate a code through the relay API:
curl -X POST "<relay>/v1/rooms/<room>/agent-join-codes" \
-H "content-type: application/json" \
--cookie "<signed-in browser cookie>" \
-d '{"note":"codex temporary join"}'
In normal use, the owner copies the returned code from the UI or API and sends only that code to the Codex user. The skill user redeems the code; they do not need owner cookies.
