openfabriq
Factory

Agents

A job description in Markdown, and the tools the agent may use on the machine.

An agent is a job description. Its settings set the model and the tools; the text below them is the brief, the same for every automation that uses the agent.

Example

openfabriq/agents/implementer/agent.md
---
description: Implements a ready issue and opens a review-ready pull request
model: opus            # optional, the model of factory.yaml otherwise
tools: [read, edit, shell]
---
# Implementation

You make the change the issue describes, prove that it works,
and deliver it as a pull request ready for review. A human merges.

## Input
- The issue and its comments.

## Output
- A pull request with the change, its tests and the proof they pass.

## Procedure
1. Read the issue and the code concerned before writing anything.
2. Stay within the issue. If the scope grows, say so in a comment.
3. Run the tests and the lint, and put the proof in the description.

Write a good brief

A good brief has four parts:

  • a role: one paragraph on what the agent does and what it never does;
  • an Input: what the agent receives;
  • an Output: precise enough to be checked;
  • a numbered Procedure.

Settings

The settings are the YAML lines between the two --- at the top of the file.

KeyWhat it saysExampleDefault
descriptionOne line, shown in the studio and in planReviews a change against the issue's contractRequired
modelsonnet, opus, haiku or a model idopusThe model of factory.yaml
toolsWhat the agent may do on the machine: read, edit, shell, web, commands (below)[read, edit, shell][read]
mcpThe MCP servers of factory.yaml it uses, and their tools{ sentry: [search_issues] }None
networkThe sites its shell, its web tool, its checks and its commands reach: packages, none, any or a list[packages, "*.sentry.io"]The network of factory.yaml

Models

An agent runs on its model (sonnet, opus, haiku or a full model id), or on the model of factory.yaml. A reviewer on a different model than the implementer does not share its blind spots: set model: opus on the reviewer of a factory that runs on sonnet.

Agents run with Claude Code, installed on the engine's machine, which pays for them with one of two credentials:

CredentialHow to set it upWho paysUse it for
Claude subscriptionLog in to Claude Code on the engine's machineYour plan's quota, shared with your own sessionsYour computer, a factory only you use
Anthropic API keyANTHROPIC_API_KEY in the engine's environmentYour Anthropic account, per tokenA server the whole team uses (how)

When both are there, the key wins; openfabriq start says which one the runs use. Either way, set limits before you start: with a key, they are real spend.

Coming soon: Codex

Support for OpenAI's Codex, so a team can run its factory on a ChatGPT plan, is planned. Need it? Open an issue with your use case.

Tools

ToolWhat the agent can do
readRead and search the code. The default when tools is left out; otherwise list it with the others, or the agent cannot read
editChange files in its checkout
shellRun commands, such as tests, a build or the app
webRead web pages of the sites its network reaches; search the web only with network: any
commandsRun the named commands of factory.yaml, and nothing else

commands is the safe middle ground: the agent runs your tests without a free shell, and the engine runs them in its own sandbox.

An agent with edit but no shell cannot run git. When its automation may open or update a pull request (create_pull_request, push_to_pull_request), the engine gives it a commit tool instead: the agent names the files and a message, the engine commits exactly those files and discards every other change in the checkout, such as a working file a command wrote. Then, as with shell, the engine runs the checks on the commit and publishes it only if the factory allows it.

Boundaries

Whatever its tools, an agent works within these boundaries:

  • Files. It reads only its checkout and the factory's skills, and writes only in its checkout.
  • Shell. Commands run in Claude Code's sandbox. They read the machine, except its secrets (the engine's tokens, ~/.ssh, ~/.config/gh, ~/.aws, the keychain). They write only in the checkout and the temporary folder, so they cannot install dependencies: do it in setup. They can open Unix sockets of their own, not the machine's: on Linux the shell does not see /run, what /tmp held when the run started, the sockets in your home folder's hidden folders, nor another run's temporary folder.
  • Environment. The agent has no GH_TOKEN, an empty gh configuration, no git credential helper, no SSH agent, and no variable that looks like a secret. It receives the values of env, never those of secrets.
  • Network. Its shell and its web tool reach only the sites of its network: by default, the package registries and GitHub. A site off the list is refused, and the repository cannot add one.

Command-line tools

openfabriq installs nothing for agents. A command-line tool an agent uses, such as a browser driver, a linter or a cloud CLI, must already be where the agent runs:

The toolHow to provide itHow the agent runs it
Is a dependency of your projectList it in your project, and install it in setupWith shell, for example pnpm exec playwright test
Is installed on the machineInstall it once on the engine's machine, on its PATHWith shell, by its name
Needs a secret, or always runs the same wayDeclare it in commands, with its secretsWith the commands tool, by name, without arguments
Has an MCP serverDeclare the server in mcpThrough the MCP tools listed in the agent's mcp

Then tell the agent when and how to use the tool, in its brief or in a skill. See Skills for command-line tools.

What a tool can do in the agent's shell

A tool run with shell has the agent's boundaries: it can read the machine, including tools installed in your home folder. Three things make it fail:

  • It writes in your home folder, for a cache, a configuration or a profile, unless an option or a variable points it to the temporary folder.
  • It needs a token. The shell never receives the values of secrets: run the tool as a command instead.
  • It needs a process that outlives the command. On Linux each command has its own sandbox, which stops what it started when it ends: a background server is gone, and the next command could not reach it anyway. Start it and use it in the same command (see Browser evidence).

Before relying on a new tool, start one manual run with openfabriq run and read its logs in the studio.

With Docker

The Docker image holds Node, git, gh, Claude Code, openfabriq and the sandbox tools, plus agent-browser and Playwright's headless Chrome for the templates' browser-evidence skill. To add a tool, install it in docker/Dockerfile, then rebuild with docker compose up -d --build.

MCP servers

agents/investigator/agent.md (settings)
mcp:
  sentry: [search_issues, get_issue_details]

The agent may call only the listed tools of servers declared in factory.yaml. See MCP servers.

Skills for one agent

Put the skills that only this agent needs in agents/<name>/skills/<skill>/SKILL.md, or <area>/agents/<name>/skills/<skill>/SKILL.md for an agent of an area. See Skills.

On this page