> ## 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

> [!NOTE]
>
> **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. Every session runs in exactly one factory; the factory supplies the session defaults and [agent definitions](https://docs.orq.ai/ai-studio/ai-engineering/agent-sessions/agent-definitions), enforces what a session may use and reach, decides which teams 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 has no restrictions and cannot be archived. Sessions created without a factory run in it.

## Create a factory

Click <kbd> Factory</kbd> 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 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. |
| **Gemini CLI** | Sets `defaultProjectTrust` to `never`. | Uses Gemini CLI's default project trust. |
| **GitHub Copilot** | Does not pre-trust the workspace, so repository `.mcp.json`, `.github/mcp.json`, and hooks are skipped. Factory MCP is still injected at `~/.copilot/mcp-config.json`. | Marks the workspace trusted so project MCP and hooks load. |
| **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** or **GitHub Copilot** in such a factory fails and names the agent. Because the default is `destructive`, **pi** and **GitHub Copilot** need 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 |
| **Gemini CLI** | Yes | Yes |
| **GitHub Copilot** | No | Yes (`session/load`; `~/.copilot` is on the volume) |
| **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 of a session 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.

**Teams** decides who can use the factory. Each factory is backed by its own project, and access is granted by adding teams to the factory; workspace Admins always have access. Factories a member cannot use are not listed for them.

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 branch pushes contact the source control provider from the computer, so an allowlist factory needs the provider's address ranges in its list.

## Budgets

Spending by a factory's sessions is capped with a [budget](https://docs.orq.ai/ai-gateway/budgets.md) of scope **Project** that targets the project backing the factory. Sessions call the AI Gateway with credentials scoped to that project, so the budget applies to every LLM call they make; once a hard limit is hit, calls return `429` and the agent's run fails with the gateway error.

Create the budget in **Settings → Budgets** or through the API:

```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": { "project": { "project_id": "<factory_project_id>" } },
    "limits": { "period": "BUDGET_PERIOD_MONTHLY", "amount": 500 }
  }'
```

## 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.

### 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 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.

## 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 direct session can clone a repository not covered by a connection with a personal access token given at session creation. Orchestrated phases require a downscoped GitHub App token, and 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 /v3/factories`, `GET /v3/factories`, `GET /v3/factories/{factory_id}`, `PATCH /v3/factories/{factory_id}`, `DELETE /v3/factories/{factory_id}` | Manage factories (`defaults.computer_template`, `policy.allowed_computer_templates`, `teams`). |
| `POST /v3/factories/{factory_id}/agent-definitions`, `GET /v3/factories/{factory_id}/agent-definitions` | Create and list factory-scoped agent definitions. |
| `GET /v2/agent-definitions/{agent_definition_id}`, `PATCH /v2/agent-definitions/{agent_definition_id}`, `DELETE /v2/agent-definitions/{agent_definition_id}` | Read, update, and delete one agent definition. |
| `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](https://docs.orq.ai/ai-studio/ai-engineering/agent-sessions/policy-profiles) and bind their ids with `factory.policy_profile_ids`. |
| `GET /v3/factories/{factory_id}/usage?window=FACTORY_USAGE_WINDOW_LAST_7_DAYS` | Usage counters; `FACTORY_USAGE_WINDOW_LAST_30_DAYS` for 30 days. |
| `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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.