Agents

Foreman leads every run and hands parts of it to specialists and custom agents.

Each factory has its own set of agents. Open Agents under a factory in the sidebar to see them in hand-off order, with Foreman at the top.

Foreman

Foreman leads every run in its factory. It’s the agent you talk to on the web, in Slack (as @handle) and in Linear, and the only one that replies to you. It works out what a request needs, hands each part to the right agent, and keeps you posted.

By default, Foreman stops and waits for you at three points:

• Specs. When a request is ambiguous enough to need a spec, Foreman asks whether you want one, and doesn’t start building until you approve it.
• Questions. When it or another agent needs an answer from you, it asks and pauses that part of the work.
• Merge requests. When the work is done, it hands you the merge request and stops. You decide whether and when to merge.

Foreman can’t be removed, and its handle can’t change after the factory is created.

Specialists

Foreman runs at most one review per piece of work. You choose which specialists a factory has when you create it. To take one out later, open it and select Remove agent under Settings. A removed specialist can’t be added back, and Foreman covers its work.

Custom agents

To add your own agent, select New on the Agents page and fill in:

• Name: up to 40 characters. You can’t rename the agent later.
• Description: Foreman reads this to decide when to hand work to the agent.
• Instructions: what the agent follows on every task, in Markdown. The editor starts with a template.
• MCP servers and Secrets: optional. See Tools and secrets.

A custom agent sees only what Foreman hands it, not the rest of the conversation. It can’t use a browser.

Edit an agent

Each agent’s page has three tabs:

• Overview: the description, and the automations that start with this agent.
• Prompt: the instructions. Changes apply from the agent’s next turn. Built-in agents also have Reset to default, which restores the original instructions once you save.
• Settings: MCP servers, secrets and Remove agent.

Every agent uses the same model, and you can’t change it.

Tools and secrets

MCP servers

MCP servers give agents more tools. Add them to the workspace on the MCPs page:

• Shared: ready-made servers. Context7 looks up library docs; an API key is optional. Linear finds, creates and updates issues and projects, and needs a Linear API key.
• Custom: a hosted server, given as JSON with its url and any headers it needs to sign in. Servers that run as a local command aren’t supported.

{
  "url": "https://mcp.acme.com/mcp",
  "headers": { "Authorization": "Bearer …" }
}

Then give the server to an agent: open the agent, go to Settings, select Add MCP server, and pick it from Workspace. A server added from the Custom tab here also joins the workspace’s MCPs. Each agent in each factory has its own list.

Secrets

Secrets belong to the workspace and live on the Secrets page at /secrets. Any signed-in user can add, edit, delete or assign them, including secrets someone else created. These actions don’t depend on your role.

To add one, select New, or New secret if the page is empty. Fill in:

• Name: required and unique across the workspace, up to 64 characters. Use uppercase letters, numbers and underscores. Start with a letter or underscore. As you type, lowercase letters become uppercase, and spaces and hyphens become underscores.
• Type: API key, Token, Password, SSH key, Certificate or Other. The default is API key.
• Value: required, up to 16,384 characters. A value made only of whitespace isn’t accepted. SSH key and Certificate use a multiline field. For other types, use Show value to check what you’ve entered.
• Description: optional, up to 200 characters. Explain what the secret is for so agents know when to use it.

Select Add secret to save it. Values are encrypted when saved, and you can’t view a saved value in the app.

To change a secret, open its three-dot menu and select Edit. You can change its Type and Description, or enter a new Value to replace the current one. Leave Value blank to keep it. Select Save changes when you’re done. You can’t rename a secret.

To assign secrets, open an agent’s Settings tab and select Add secret under Secrets. Search the workspace list by name, type or description, then select Add beside each secret you want. Each addition saves immediately. You can assign up to 500 secrets to an agent. Each agent in each factory has its own assignments.

You can’t create a secret in this picker. Select Manage secrets, or Go to Secrets if the workspace has none, to add it on the Secrets page. Then return to the agent to assign it. Use the trash button beside an assigned secret to remove it from that agent. The secret stays in the workspace and other agents keep their assignments.

To delete a secret from the workspace, select Delete from its three-dot menu and confirm. You can’t undo this. Deleting it removes its assignments from every agent in every factory. Those agents lose the credential for commands that need it, so assign a replacement if they still need access.

During a run, an agent’s secrets sit in a private file in the sandbox. The agent knows each secret’s name and description but not its value, and loads the file only in the command that needs it. Agents are instructed never to print a secret or write one into the repository, a commit, a comment or a message.

Working in the sandbox

Runs happen in a Vercel Sandbox. Foreman and the agents it hands work to share it.

• Code. If the factory has a repository, the agents clone it into the sandbox when they need the code. git and glab are signed in as the GitLab account connected to the workspace, so commits and merge requests come from that account.
• Merge requests. Agents work on factory/… branches and open merge requests as drafts. They never merge or approve one.
• Reviews. Foreman posts only the review findings that need a person’s judgment, as comments on the merge request.
• UI checks. Foreman and Implement have a headless Chromium browser. They run the app’s dev server in the sandbox, record video and screenshots, and add them to the merge request description. An app that needs missing environment variables, a database or a signed-in user can’t be checked this way, and the agent says so.