On the relay

agent-relay on is the CLI entry point for running an agent inside the relay sandbox, with mounted services and permission-aware workspace access.

Launch an agent

agent-relay on codex --agent reviewer -- --model gpt-5.4

Common options:

• --agent <name> sets the relay identity name.
• --workspace <id> joins an existing relay workspace.
• --port-auth <port> overrides the Relayauth port.
• --port-file <port> overrides the Relayfile port.
• any extra args after -- are passed through to the underlying CLI.

Preview or diagnose the environment

agent-relay on --scan
agent-relay on --doctor

• --scan previews what the agent will be able to see before launch.
• --doctor checks prerequisites and exits without starting a session.

Stop relay services

agent-relay off

Use off when you are done with the mounted relay environment and want a clean shutdown.

See also