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, 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.
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.
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 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 of scope Factory. Session API keys carry the label factory=<factory_id>, 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:

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

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

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

Overview

Managed Agents

Context Management

Test & Evaluate

Playground