> ## 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.
# Factories and Connections
> Govern agent sessions with factories: session defaults, allowed agents, models, computers and repositories, concurrency and session-hour limits, CIDR egress allowlists, project access, factory budgets, and per-workspace GitHub connections.
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.
A **Factory** is the unit of governance for [agent sessions](/docs/ai-studio/ai-engineering/agent-sessions/overview). Every session runs in exactly one factory; the factory supplies the session defaults, enforces what a session may use and reach, decides which projects can use it, and is the scope of its spending budget and usage analytics. **Connections** link a workspace to a source control provider (GitHub today) so sessions can clone private repositories and open pull requests.
Factories are managed by workspace Admins under **Managed Agents** > **Factories**. Connections are managed under **Settings** > **Integrations**. Developers and Researchers can see them.
## Default factory
Every workspace gets a **Default** factory the first time a session is created or listed. It is shared with all projects, has no restrictions, and cannot be archived. Sessions created without a factory run in it.
## Create a factory
Click Factory on the **Factories** page. The same form edits an existing factory from its **Configuration** tab.
**General**
| Field | Description |
| --------------- | ------------------------------ |
| **Name** | Workspace-unique display name. |
| **Description** | Free text. |
**Session defaults** apply when a session is created without the field:
| Field | Description |
| -------------------------- | -------------------------------------------------------------------------------- |
| **Computer** | Default isolation, for example `coding-session-runc` or `coding-session-gvisor`. |
| **Agent** | Default agent. When unset, sessions must name an agent. |
| **Model** | Default gateway model id. |
| **Idle timeout (seconds)** | `0` keeps the platform default of 1800; otherwise at least 60. |
| **Clone depth** | `0` clones the full history. |
**Policy** restricts what sessions in the factory may use. Empty lists mean no restriction:
| Field | Description |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Allowed agents** | Agents sessions may run. |
| **Allowed models** | Gateway model ids sessions may use (the session model and per-run overrides). |
| **Allowed computers** | Computer templates sessions may be created with. |
| **Allowed connections** | GitHub connections sessions may clone through. Repositories outside the connected accounts are rejected. Empty allows any connection of the workspace. |
| **Max concurrent sessions** | Live sessions (creating, ready, running, pausing, paused) allowed at once. `0` means unlimited. Creating or resuming a session over the limit returns `429`. |
| **Max concurrent builds** | Computer blueprint builds allowed at once. Defaults to `1`; builds do not count as agent sessions. |
| **Max session hours** | Ready sessions older than this are paused; the next message resumes them. `0` turns it off. |
| **Egress mode** | **Unrestricted** or **Allowlist**; see [Egress](#egress). |
| **CIDR allowlist** | One CIDR per line, used when the egress mode is **Allowlist**. |
| **Allowed repository prefixes** | URL prefixes sessions may clone, for example `https://github.com/orq-ai/`. |
| **Trust repository agent config** | When on, sessions load repository-provided agent configuration. Off by default. See [Repository agent configuration](#repository-agent-configuration). |
| **Approvals** | Plan, tool-call, and merge gates. Tool-call `none` auto-allows; `destructive` pauses `edit`, `delete`, `move`, and `execute`; `all` pauses every tool. See [Approvals](#approvals). |
### Repository agent configuration
Factory-provided skills and MCP servers, plus repository `CLAUDE.md` and `AGENTS.md` instruction files, remain available in both modes. The toggle controls configuration supplied by the repository that can run hooks, add tools, or change permissions.
| Agent | Off (default) | On |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| **Claude Code** | Ignores `.claude/settings.json`, `.claude/settings.local.json`, and repository `.mcp.json`. | Loads project and local settings and repository MCP servers. |
| **Codex** | Marks the repository untrusted, so repository `.codex/` config, hooks, and rules are ignored. | Marks the repository trusted and loads repository `.codex/` configuration. |
| **opencode** | Ignores project `opencode.json` and `opencode.jsonc` files and project `.opencode/` configuration, agents, commands, and plugins. | Uses normal project configuration discovery. |
| **orq** | No effect. The agent does not execute repository-local configuration. | No effect. |
| **pi** | Does not load repository `.pi/` configuration or extensions. | Loads repository `.pi/` configuration and extensions. |
### Approvals
Factory `policy.approvals.tool_calls` is `none`, `destructive` (default), or `all`. A factory that is not `none` can only start agents that can emit tool-call permission requests. Session creation with **pi** in such a factory fails and names **pi**. Because the default is `destructive`, **pi** needs a factory with tool-call approvals set to `none`.
| Agent | Tool-call approvals | Session resume |
| --------------- | ------------------- | -------------------------------------------------- |
| **Claude Code** | Yes | Yes (`session/load`; `~/.claude` is on the volume) |
| **Codex** | Yes | Yes |
| **opencode** | Yes | Yes |
| **orq** | Yes | Yes |
| **pi** | No | Yes (JSONL on the volume) |
The conversation card for a tool-call approval shows the tool title, kind, and a 4 KB argument preview, with **Allow once**, **Allow always**, and **Reject**. Unanswered requests time out after 15 minutes and are rejected.
When `approvals.plan` is on, the first run is plan-only. If the agent emits an ACP plan, that plan is what the approval card shows; otherwise the last assistant message is used.
**Onboarding a registry agent**: package the binary in `images/agent-session-runtime/flake.nix`, wire gateway env the same way as an existing adapter, add an `ACPLaunch` entry with `tool_approvals` and `load_session`, then run the same-task parity checklist (events, resume, cancel, approvals) before deleting any previous launch path.
**Session identity** under **Governance** controls short-lived OIDC tokens for sessions in the **Factory**. It is disabled by default. Configure up to 10 relying-party audiences; an empty list uses `orq-agent-sessions`. See [Session identity tokens](/docs/ai-studio/ai-engineering/agent-sessions/session-identity) for claims, rotation, and cloud trust policies.
**Access control** decides which projects can use the factory: **All projects** or **Custom** with a project selection. A member can create a session in a factory only when the session's project is covered; factories a member cannot use are not listed for them. This mirrors sharing elsewhere in **Orq.ai**; teams get access through their project memberships.
Click **Create factory**. Policy changes apply to new sessions and runs; existing sessions keep working.
## Egress
Session computers can always reach DNS and the **AI Gateway**. What else they can reach depends on the factory:
* **Unrestricted**: the public internet (private address ranges are always blocked). This is the default.
* **Allowlist**: only the listed CIDRs. Everything else, including `github.com`, is blocked unless its address range is listed.
Allowlists are enforced with Kubernetes network policies on the computer pods, which match IP ranges only; hostnames cannot be allowlisted. Repository cloning and pull requests use the session's git token from inside the computer, so an allowlist factory needs the source control provider's address ranges in its list.
## Budgets
Spending by a factory's sessions is capped with a [budget](/docs/ai-gateway/budgets) of scope **Factory**. Session API keys carry the label `factory=`, and the gateway enforces the budget on every LLM call they make; once a hard limit is hit, calls return `429` and the agent's run fails with the gateway error.
Factory budgets are created through the API (the **Budgets** UI does not offer the scope yet) and linked to the factory with `budget_id`:
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://my.orq.ai/v2/budgets \
-H "Authorization: Bearer $ORQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"scope": { "factory": { "factory_id": "fac_01H..." } },
"limits": { "period": "BUDGET_PERIOD_MONTHLY", "amount": 500 }
}'
```
Then set `budget_id` on the factory with `PATCH /v2/factories/{factory_id}`.
## Usage
The **Usage** tab of a factory shows, for the last 7 or 30 days, sessions by status, sessions created, runs, sessions by agent, and the most used repositories. Token and cost analytics of a factory are available in [Traces](/docs/ai-studio/observability/traces) by filtering on the span attribute `orq.api_key.label.factory`.
### Session insights
Attach the built-in `orq_session_insights` scorer with `input_mode` set to `FACTORY_SCORER_INPUT_MODE_TRANSCRIPT`. After each completed run, it classifies the work category and outcome, records friction points and suggestions, and identifies skills, knowledge notes, or blueprint knowledge that the agent used or ignored.
The session **Insights** tab shows the result for each run. Factory analytics aggregate outcome distribution, top friction categories, and the latest suggestions. A `failed` insight also counts toward the factory's existing self-improvement threshold.
## Knowledge notes
Use **Factory** > **Settings** > **Knowledge** to create short, reusable instructions for a factory. Each note has a title, a trigger phrase that tells the agent when it applies, a body of up to 4 KB, and an optional repository URL. Disabled notes remain drafts.
Attach a note to the factory to inject it into new sessions. Notes with a repository URL are injected only when the session uses that repository. The runtime writes each note to `.orq/knowledge/.md` in the cloned repository and adds `title — trigger` to `AGENTS.md` so the agent can discover the relevant note without loading every body up front.
## Archive a factory
**Archive** on the factory page stops new sessions from being created in it; existing sessions keep working. The default factory cannot be archived, and a factory cannot be deleted while it has live sessions.
## Connections
A connection is an installation of the **Orq.ai** GitHub App on a GitHub user or organization. It lets sessions clone the repositories the installation covers and lets **Orq.ai** open pull requests on them. One workspace can hold several connections; a connection is used by every factory of the workspace unless a factory restricts **Allowed connections**.
### Connect GitHub
1. Go to **Settings** > **Integrations** and click **Connect GitHub**.
2. On GitHub, choose the account and either **All repositories** or a selection, then install the App.
3. GitHub returns to **Orq.ai**; the new connection appears in the list with its **Account** and **Repository access**.
Install the App on every account whose repositories sessions should work on. When a session is created, the clone token is minted from the connection of the repository owner; a repository no connection covers can still be cloned with a personal access token given at session creation, but pull requests require a connection.
A connection shows as **Suspended** when the installation was suspended on GitHub (no tokens can be minted until it is unsuspended) and as **Revoked** after it was removed in **Orq.ai**. Remove a connection from the list; sessions that rely on it lose repository access.
### Factories and connections
Use **Allowed connections** in a factory's policy to limit its sessions to specific GitHub accounts, and **Allowed repository prefixes** to limit them to specific organizations or repositories within those accounts.
### API
| Method and path | Purpose |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `POST /v2/factories`, `GET /v2/factories`, `GET /v2/factories/{factory_id}`, `PATCH /v2/factories/{factory_id}`, `DELETE /v2/factories/{factory_id}` | Manage factories (`defaults.computer_template`, `policy.allowed_computer_templates`, `sharing`, `budget_id`). |
| `POST /v2/policy-profiles`, `GET /v2/policy-profiles`, `PATCH /v2/policy-profiles/{policy_profile_id}`, `DELETE /v2/policy-profiles/{policy_profile_id}` | Manage reusable [policy profiles](/docs/ai-studio/ai-engineering/agent-sessions/policy-profiles) and bind their ids with `factory.policy_profile_ids`. |
| `GET /v2/factories/{factory_id}/usage?window=FACTORY_USAGE_WINDOW_LAST_7_DAYS` | Usage counters; `FACTORY_USAGE_WINDOW_LAST_30_DAYS` for 30 days. |
| `POST /v2/factories/{factory_id}/knowledge-notes`, `GET /v2/factories/{factory_id}/knowledge-notes` | Create and list factory knowledge notes. |
| `GET /v2/factory-knowledge-notes/{note_id}`, `PATCH /v2/factory-knowledge-notes/{note_id}`, `DELETE /v2/factory-knowledge-notes/{note_id}` | Read, update, and delete one knowledge note. |
| `POST /v2/scm-connections/github/installations` | Start the GitHub App installation; returns `install_url` to open in a browser. |
| `GET /v2/scm-connections`, `GET /v2/scm-connections/{connection_id}`, `DELETE /v2/scm-connections/{connection_id}` | List, get, and remove connections. |
| `GET /v2/scm-connections/{connection_id}/repositories` | Repositories the connection can access. |
Factory and connection writes require the Admin role or a management key with the matching permissions.
Prepare dependencies and inspect build snapshots under **Factory** > **Settings** > **Computer blueprints**. See [Computer blueprints](/docs/ai-studio/ai-engineering/agent-sessions/computer-blueprints).