Architecture

The platform has three parts you install: a Polarion application (the views your people use), the Agent Runner (a service that runs the agents), and PocketBase (a small database for operational state). Agents that write code also get an OpenSandbox sandbox per task. Everything else is a system you already have: Polarion itself, a model provider, and the tools you connect over MCP.

Teal: Polarion. Violet: the Agent Runner and what it operates. Blue: external systems. Dashed: sandbox traffic, which leaves only through allowed routes.

Components

Component	What it is	What it does
Agentic app	A Polarion application (identifier agentic)	Adds the Team page, AI Reports, Agency and Administration topics, form extensions (task panel, provenance, agent brain, MCP server panel) and the Agent chat sidebar. Server scripts add and remove project roles for bot users when you hire or let go.
Agent Pool project	A Polarion project	Holds the agents, their skills and the MCP connections. Each agent is a work item with its own Polarion bot user.
Work projects	Your Polarion projects	Hold engagements (hired agents), tasks, agent runs, memories and everything the agents produce.
Watcher	Part of the runner	Polls Polarion for tasks assigned to hired agents and starts runs.
Agent loop	Part of the runner	The built-in harness: builds the instructions and the task prompt and lets the model work with its tools.
Sandbox harnesses	Claude Code or Codex	Run inside the task’s sandbox for agents that build and test code.
MCP gateway	Part of the runner	The only way an agent reaches tools: Polarion tools and the tools of connected MCP servers. Checks grants, scope and policy, holds writes for approval and records every call.
Sandbox entrance	A second listener of the runner	The only address a sandbox can reach in the runner: the MCP gateway and the git proxy.
PocketBase	A small database next to the runner	Operational state: live events, held approvals, standing rules, watcher bookkeeping, chats and encrypted connection credentials.
OpenSandbox	Sandbox server on a Docker host	One sandbox per task, with deny-by-default egress, a read-only internet proxy and a credential vault for the model key.

See Data model for the work item types, and MCP gateway for how tool calls are controlled.

Polarion is the system of record

Everything that matters for audit and traceability lives in Polarion, as ordinary work items with links, comments and history:

• Who the agents are, which skills they have and which systems they may use (Agent Pool).
• Who hired which agent into which project, with which budget and which grants (engagements).
• The work itself: tasks, the comment thread with the agent, questions and answers, approvals.
• Every run of an agent: model, tokens, cost, outcome, what it read and changed, and the full transcript as an attachment (agent runs).
• Every artifact an agent creates, marked as AI generated and linked to its task and run.

Agents write through their own Polarion user, so Polarion shows them as the author and enforces their project permissions. PocketBase holds nothing that you need to reconstruct what happened in a project.

What lives where

Data	Polarion	PocketBase
Agents, skills, MCP connections and their tool policies	Yes	No
Engagements: supervisor, budget, spent, grants, scopes, standing approvals	Yes	A copy of standing approvals, so a re-hire restores them
Tasks, comments, questions, answers, approval decisions (as comments)	Yes	No
Agent runs: cost, tokens, outcome, ledger, sandbox facts, transcripts	Yes	A short run record for the live view
Live activity (text as it streams, tool calls)	No	Yes (events)
Held write calls with their exact arguments and results	Decision and result as task comments	Yes (approvals)
Credentials: model key, agent tokens, connection credentials	Only the secret’s name (connections)	Yes, encrypted (secrets)
Sidebar chats	No (until you create a proposed task)	Yes (chats)
Watcher bookkeeping	No	Yes (task_state)

How one task flows

1. You assign a task to a hired agent, the normal Polarion way (the assignee is the agent’s bot user).
2. The watcher notices the new assignment on its next poll and starts a run. Runs are serialized per task and per agent.
3. The runner prepares the run. It reads the agent, its approved skills, the engagement, active memories, the team and the granted connections, and builds the instructions and the task prompt (see Agent runs). It opens a gateway session with a fresh run token.
4. The agent works. The built-in loop (or Claude Code / Codex in the task’s sandbox) calls the model and uses tools only through the MCP gateway. Polarion tools act as the agent’s bot user.
5. The gateway enforces policy. Reads run. Writes to connected systems that need approval, and changes to items written by people, are held: the task goes to waiting_input and to the supervisor.
6. The agent finishes by submitting for approval, asking you a question, or waiting for delegated sub-tasks. The task panel shows the result, the questions as a form, and any held changes.
7. The runner records the run as an agentRun work item: cost, tokens, outcome, the ledger of everything it touched, the gateway calls and the transcript. The engagement’s spent amount goes up.
8. You decide. Approve the task, send it back with feedback, answer the questions, or approve or deny held changes. Each decision wakes the agent again with the matching trigger.

Deployment view

Piece	Where it runs	Talks to
Agentic app	Inside Polarion (installed as an application)	The runner’s HTTP API, from the user’s browser
Agent Runner	A container (Python service)	Polarion REST, PocketBase, the model endpoint, MCP servers, git hosts, OpenSandbox
PocketBase	A container next to the runner	Only the runner
OpenSandbox server	A Docker host	Starts sandboxes; the runner manages them through its API
Sandboxes	Containers on that Docker host	The sandbox entrance, the model endpoint, allowed websites

• Serve the runner under the same origin as Polarion (a reverse-proxy path). The views send the user’s Polarion session token, and the runner checks it together with the session cookie against Polarion.
• The sandbox entrance listens on the Docker bridge address, so sandboxes reach the gateway and the git proxy but not the runner’s main API.
• The runner needs one model endpoint and key. Models are configured per agent as provider:model (Anthropic, OpenAI and Google are supported), served by a model provider or a company LLM gateway.

Note

Sandboxes are optional. Without OpenSandbox, every agent uses the built-in harness in the runner. See Sandboxes and Installation.