> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Sessions
> Run Claude Code, Codex, Gemini CLI, opencode, orq, or pi in an isolated computer on a repository, with every LLM call routed through the AI Gateway and a conversation that survives days.
Beta
**Agent Sessions** is in private preview. The feature is enabled per workspace by the **Orq.ai** team and the API is not part of the public SDKs yet. Behavior and field names can still change.
**Agent Sessions** run a coding agent inside an isolated computer that holds a clone of a repository. Send a task, watch the agent work (tool calls, file edits, output) in real time, keep the conversation going for as long as the work takes, review the changes, and open a pull request from the session. **Factories** give administrators control over which agents, models, repositories, and network destinations a team can use, and how much it can spend.
Create a session, chat with the agent, review changes, open a pull request, and drive sessions through the API.
Governance: session defaults, policies, egress, budgets, project access, and GitHub connections.
Use short-lived OIDC tokens for keyless access to cloud services and Vault.
## Agents
A session runs one agent. The agent is chosen when the session is created and can be overridden per run.
| Agent | Gateway endpoint used by the agent | Notes |
| --------------- | ------------------------------------ | -------------------------------------------------------------------------------------- |
| **Claude Code** | `/v3/anthropic` (Anthropic Messages) | Session transcript is ACP `session/update`. LLM calls go through the gateway. |
| **Codex** | `/v3/router` (Responses API) | Session transcript is ACP `session/update`. The Responses API is the LLM gateway only. |
| **opencode** | `/v3/router` (OpenAI-compatible) | Session transcript is ACP `session/update`. |
| **orq** | `/v3/router` | The first-party **Orq.ai** agent harness with native file and shell tools. |
| **pi** | `/v3/router` (Responses API) | Session transcript is ACP `session/update`. The Responses API is the LLM gateway only. |
Any model available through the [**AI Gateway**](/docs/ai-gateway/get-started/introduction) can be used, referenced by its gateway id (for example `anthropic/claude-sonnet-4-6` or `openai/gpt-4o`). When no model is given, the factory default applies, then the runtime default `anthropic/claude-sonnet-5`.
## How it works
### Computers and isolation
A computer is the isolated machine a session runs on. A computer template configures that machine and is backed by a Kubernetes `SandboxTemplate` custom resource.
| Computer template | Isolation | Description |
| ----------------------- | --------- | -------------------------------------------------------------------- |
| `coding-session-runc` | runc | Standard container isolation. |
| `coding-session-gvisor` | gVisor | Kernel-isolated computer. Recommended for multi-tenant environments. |
Which computer templates are available depends on the cluster; list them with `GET /v2/computer-templates`. Inside the computer the agent runs as a non-root user on a read-only root filesystem, with the repository cloned to `/workspace/repo` on a persistent volume. Tool-call approvals follow the factory policy; see [Approvals](/docs/ai-studio/ai-engineering/agent-sessions/factories-and-connections#approvals).
Network egress from the computer is limited to DNS, the **AI Gateway**, and the public internet (private address ranges are always blocked). A factory can narrow this further to an allowlist of CIDRs; see [Egress](/docs/ai-studio/ai-engineering/agent-sessions/factories-and-connections#egress).
### LLM calls go through the gateway
Every session gets its own API key, minted when the session is created and revoked when the session is deleted. The key is scoped to the session's project, named `agent-session:`, and labelled with the session's factory. The agent inside the computer receives that key and the gateway URL in memory only; credentials are never written to the pod specification.
As a result every LLM call made by the agent shows up in [Traces](/docs/ai-studio/observability/traces) and [Logs](/docs/ai-studio/observability/logs) under that key, and factory [budgets](/docs/ai-studio/ai-engineering/agent-sessions/factories-and-connections#budgets) are enforced by the gateway like any other budget.
### Repository access
Repositories are cloned over HTTPS. For private repositories the clone token comes from a [GitHub connection](/docs/ai-studio/ai-engineering/agent-sessions/factories-and-connections#connections) of the workspace (a short-lived installation token of the **Orq.ai** GitHub App, resolved from the repository owner), or from a personal access token passed when the session is created. Tokens are handed to the computer at attach time and are never logged or exposed to the model.
Clones keep the full history with lazily fetched file contents, so `git log` and `git blame` work inside the session. A shallow clone depth can be requested per session.
### Lifecycle
```
creating -> ready -> running -> ready -> ... -> paused -> (next message) -> ready
|
+-> failed any state -> deleted
```
| Status | Meaning |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Creating** | The computer is being provisioned (a warm pool usually makes this take seconds). Also shown while a paused session resumes. |
| **Ready** | The agent is idle and waiting for a message. |
| **Running** | A run (one prompt, one agent turn) is in progress. Only one run per session at a time. |
| **Pausing / Paused** | The pod has been removed; the workspace volume (repository, agent state) is kept. Paused sessions cost no compute. |
| **Failed** | Provisioning failed. The error is in the session events. |
| **Deleted** | The computer and volume are gone and the session key is revoked. |
State changes are published as session events (`session.provisioning`, `session.ready`, `repo.cloning`, `repo.cloned`, `run.queued`, `run.started`, `run.finished`, `session.pausing`, `session.paused`, `session.resuming`, `session.resumed`, `session.failed`, `session.deleted`) and are shown as the status line of the session page.
**Idle auto-pause.** A ready session that receives no message for its idle timeout (default 30 minutes, minimum 60 seconds, configurable per session and per factory) is paused automatically. Ready sessions older than a factory's maximum session hours are paused as well.
**Auto-resume.** Sending a message to a paused session resumes it first (typically a few seconds) and then starts the run. There is no need to resume explicitly.
### Conversation continuity
Every message continues the agent's previous conversation in that session, including after a pause and resume: the agent remembers earlier turns, the repository state, and its own notes on the persistent volume. Start a fresh conversation on the same computer with the **New conversation** toggle in the composer (`new_conversation: true` in the API).
## Limits
| Limit | Value |
| ----------------------------------------------------------------------- | -------------------------------------------------------------------- |
| Live sessions per workspace (creating, ready, running, pausing, paused) | 20 by default; operators can change it. Creating more returns `429`. |
| Live sessions per factory | Set by the factory's **Max concurrent sessions** (0 = unlimited). |
| Concurrent runs per session | 1 |
| Prompt length | 32,000 characters |
| Idle timeout | At least 60 seconds |
| Repository URL | `https://` only, no embedded credentials |
| Workspace diff | Unified diff capped at 512 KiB; file list capped at 2,000 files |
| Egress allowlists | CIDRs only (no hostnames) |
## Get started
Open **Managed Agents** > **Factories**, select a factory, then open its **Sessions** tab.