If you don't have the CLI yet, start here.
curl -fsSL https://cli.orq.ai/install.sh | sh
curl -fsSL https://cli.orq.ai/install.sh | sh
curl -fsSL https://cli.orq.ai/install.sh | sh
curl -fsSL https://cli.orq.ai/install.sh | sh
That's all orq launch needs. There's no project to create and no config to write first. Introducing the Orq.ai CLI covers what else the binary does.
Eight agents are supported today.
Everything after -- is passed through to the agent untouched, so your usual flags still work. That includes each agent's headless mode, which turns a one-shot, scripted run through the Orq.ai Gateway into a single line.
orq launch claude -- -p "summarize yesterday's failed traces"
orq launch claude -- -p "summarize yesterday's failed traces"
orq launch claude -- -p "summarize yesterday's failed traces"
orq launch claude -- -p "summarize yesterday's failed traces"
Once you've run orq auth login, that's all it needs. In CI there's no browser to log in with, so pass an API key through the environment instead. Same command otherwise, and the environment variable takes precedence over your session.
ORQ_API_KEY=<your_key> orq launch claude -- -p "summarize yesterday's failed traces"
ORQ_API_KEY=<your_key> orq launch claude -- -p "summarize yesterday's failed traces"
ORQ_API_KEY=<your_key> orq launch claude -- -p "summarize yesterday's failed traces"
ORQ_API_KEY=<your_key> orq launch claude -- -p "summarize yesterday's failed traces"
Launch is for temporary sessions. If you already know you want your coding agents routed through Orq.ai on this machine every time, orq connect is the command for that, and orq connect skills installs the skills for good. The CLI reference documents both, along with every flag on launch.
What it actually does
--dry-run prints the resolved command and environment without starting the agent.
$ orq launch claude --dry-run
binary: claude
args: --mcp-config /var/folders/.../orq-claude-mcp-3908269829/mcp.json
env:
ANTHROPIC_API_KEY=
ANTHROPIC_AUTH_TOKEN=<redacted>
ANTHROPIC_BASE_URL=https://my.orq.ai/v3/anthropic
ANTHROPIC_DEFAULT_HAIKU_MODEL=anthropic/claude-haiku-4-5
ANTHROPIC_DEFAULT_OPUS_MODEL=anthropic/claude-opus-5
ANTHROPIC_DEFAULT_SONNET_MODEL=anthropic/claude-sonnet-5
ANTHROPIC_MODEL=anthropic/claude-sonnet-5
ANTHROPIC_SMALL_FAST_MODEL=anthropic/claude-haiku-4-5
ORQ_API_KEY=<redacted>
ORQ_SERVER=https://my.orq.ai
tempdir: /var/folders/.../orq-claude-mcp-3908269829
note: a real run links 14 skills into ~/.claude/skills for the session and removes them on exit
$ orq launch claude --dry-run
binary: claude
args: --mcp-config /var/folders/.../orq-claude-mcp-3908269829/mcp.json
env:
ANTHROPIC_API_KEY=
ANTHROPIC_AUTH_TOKEN=<redacted>
ANTHROPIC_BASE_URL=https://my.orq.ai/v3/anthropic
ANTHROPIC_DEFAULT_HAIKU_MODEL=anthropic/claude-haiku-4-5
ANTHROPIC_DEFAULT_OPUS_MODEL=anthropic/claude-opus-5
ANTHROPIC_DEFAULT_SONNET_MODEL=anthropic/claude-sonnet-5
ANTHROPIC_MODEL=anthropic/claude-sonnet-5
ANTHROPIC_SMALL_FAST_MODEL=anthropic/claude-haiku-4-5
ORQ_API_KEY=<redacted>
ORQ_SERVER=https://my.orq.ai
tempdir: /var/folders/.../orq-claude-mcp-3908269829
note: a real run links 14 skills into ~/.claude/skills for the session and removes them on exit
$ orq launch claude --dry-run
binary: claude
args: --mcp-config /var/folders/.../orq-claude-mcp-3908269829/mcp.json
env:
ANTHROPIC_API_KEY=
ANTHROPIC_AUTH_TOKEN=<redacted>
ANTHROPIC_BASE_URL=https://my.orq.ai/v3/anthropic
ANTHROPIC_DEFAULT_HAIKU_MODEL=anthropic/claude-haiku-4-5
ANTHROPIC_DEFAULT_OPUS_MODEL=anthropic/claude-opus-5
ANTHROPIC_DEFAULT_SONNET_MODEL=anthropic/claude-sonnet-5
ANTHROPIC_MODEL=anthropic/claude-sonnet-5
ANTHROPIC_SMALL_FAST_MODEL=anthropic/claude-haiku-4-5
ORQ_API_KEY=<redacted>
ORQ_SERVER=https://my.orq.ai
tempdir: /var/folders/.../orq-claude-mcp-3908269829
note: a real run links 14 skills into ~/.claude/skills for the session and removes them on exit
$ orq launch claude --dry-run
binary: claude
args: --mcp-config /var/folders/.../orq-claude-mcp-3908269829/mcp.json
env:
ANTHROPIC_API_KEY=
ANTHROPIC_AUTH_TOKEN=<redacted>
ANTHROPIC_BASE_URL=https://my.orq.ai/v3/anthropic
ANTHROPIC_DEFAULT_HAIKU_MODEL=anthropic/claude-haiku-4-5
ANTHROPIC_DEFAULT_OPUS_MODEL=anthropic/claude-opus-5
ANTHROPIC_DEFAULT_SONNET_MODEL=anthropic/claude-sonnet-5
ANTHROPIC_MODEL=anthropic/claude-sonnet-5
ANTHROPIC_SMALL_FAST_MODEL=anthropic/claude-haiku-4-5
ORQ_API_KEY=<redacted>
ORQ_SERVER=https://my.orq.ai
tempdir: /var/folders/.../orq-claude-mcp-3908269829
note: a real run links 14 skills into ~/.claude/skills for the session and removes them on exit
The base URL points at the Orq.ai Gateway, the model names are workspace models, and the fast and slow model slots are filled so the agent's own routing decisions stay inside your catalogue.
For an agent configured through flags rather than environment, the same command shows the flags.
$ orq launch codex --dry-run
binary: codex
args: -c model="openai/gpt-5.6-terra" -c model_provider="orq"
-c model_providers.orq.name="Orq AI Gateway"
-c model_providers.orq.base_url="https://my.orq.ai/v3/router"
-c model_providers.orq.env_key="ORQ_API_KEY"
-c model_providers.orq.wire_api="responses"
-c model_catalog_json="/var/folders/.../model-catalog.json"
-c mcp_servers.orq-workspace.url="https://my.orq.ai/v2/mcp"$ orq launch codex --dry-run
binary: codex
args: -c model="openai/gpt-5.6-terra" -c model_provider="orq"
-c model_providers.orq.name="Orq AI Gateway"
-c model_providers.orq.base_url="https://my.orq.ai/v3/router"
-c model_providers.orq.env_key="ORQ_API_KEY"
-c model_providers.orq.wire_api="responses"
-c model_catalog_json="/var/folders/.../model-catalog.json"
-c mcp_servers.orq-workspace.url="https://my.orq.ai/v2/mcp"$ orq launch codex --dry-run
binary: codex
args: -c model="openai/gpt-5.6-terra" -c model_provider="orq"
-c model_providers.orq.name="Orq AI Gateway"
-c model_providers.orq.base_url="https://my.orq.ai/v3/router"
-c model_providers.orq.env_key="ORQ_API_KEY"
-c model_providers.orq.wire_api="responses"
-c model_catalog_json="/var/folders/.../model-catalog.json"
-c mcp_servers.orq-workspace.url="https://my.orq.ai/v2/mcp"$ orq launch codex --dry-run
binary: codex
args: -c model="openai/gpt-5.6-terra" -c model_provider="orq"
-c model_providers.orq.name="Orq AI Gateway"
-c model_providers.orq.base_url="https://my.orq.ai/v3/router"
-c model_providers.orq.env_key="ORQ_API_KEY"
-c model_providers.orq.wire_api="responses"
-c model_catalog_json="/var/folders/.../model-catalog.json"
-c mcp_servers.orq-workspace.url="https://my.orq.ai/v2/mcp"Note the generated model catalogue. The agent's model picker offers what your workspace allows, so governance you already set in the platform holds inside the coding session too.
What routing buys you
Every model call goes through the Gateway, which means a coding session is governed like production traffic rather than running as a side channel. Whatever you have configured there applies to it.
Every call is traced, with its cost, token counts, latency, and the model that served it.
Spend counts against your budgets and rate limits, so a session left running overnight cannot outspend its cap.
Routing rules and the Smart Router still choose the model, with fallbacks and retries when a provider fails.
Guardrails run on the session's traffic the same way they run on everything else.
The model picker is the workspace's own catalogue, so an agent cannot reach a provider or model you have not enabled.
You do not have to instrument any of it. Start a session and it shows up in orq traces alongside everything else.
Skills, borrowed, not installed
Every launched agent gets the Orq.ai Skills. They're linked into the skills directory the agent reads when it starts, and removed again when it exits. They ship inside the CLI binary, so this works offline.
That's the difference between launch and orq connect. Launch borrows; connect installs. If you want them permanently, orq connect skills is one command. If you're trying Orq.ai for the first time, or you're on a machine that isn't yours, borrowing is the right default.
--no-skills opts out, and it isn't gated on MCP.
The workspace comes along
--mcp is on by default, so the Orq.ai MCP server is wired into the session and the agent can reach your workspace tools without you registering anything. It can read traces, deployments, datasets, and evaluators from a session you started seconds ago. --no-mcp turns it off when you want a plain routed session.
Which credential it uses
Four sources, first match wins.
The API-key profile in force (--profile, ORQ_PROFILE, or orq auth profile use). The login session is not read at all.
ORQ_API_KEY from the environment, which likewise overrides the workspace picked by orq auth login.
The key orq setup minted, when it belongs to the workspace shown by orq workspace and has not expired.
The active workspace token from your orq auth login session.
Session tokens expire after an hour, so orq setup is the way to mint a durable key for anything long-running.
Model and base URL
--model picks the Gateway model for the session, in provider/model_id form.
--server points the session at a different Gateway, which is how you run against a self-hosted or on-prem deployment. It is a global flag, so it goes before the subcommand.
When to use it
Two cases. The first is trying something without configuring it. Run one session, see whether routing your coding agent through the Orq.ai Gateway earns its place, then make it permanent with orq connect if it does.
The second is anywhere a session is disposable by design. CI jobs, containers, a colleague's machine, a scheduled task that runs an agent headless against your workspace. Each run gets the Gateway, the workspace tools, and the skills, then leaves the machine as it found it.
Learn more
The CLI reference on docs.orq.ai documents every command and flag, and the CLI itself is on GitHub, which is where issues and suggestions go.
Run orq launch claude, and add --dry-run first if you want to see exactly what it sets.
