Factories and 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. Every session runs in exactly one factory; the factory supplies the session defaults and 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 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 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.
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.
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.

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

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

Go to Settings > Integrations and click Connect GitHub.
On GitHub, choose the account and either All repositories or a selection, then install the App.
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.

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

Overview

Managed Agents

Context Management

Test & Evaluate

Chat