---
title: Agents
description: 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

| Specialist | What it does |
| --- | --- |
| **Triage** | Researches a request and reproduces bugs where it can, then reports the type, severity, findings and next step. It doesn't change files. |
| **Spec** | Writes a spec: goal, approach, files, acceptance criteria, what's out of scope and open questions. It doesn't change files. |
| **Implement** | Makes the smallest change that does the job, runs the relevant tests, type check or lint, and checks web UI changes in a browser. |
| **Review** | Looks for bugs, regressions, edge cases, security issues and missing tests, and ranks what it finds by severity. It doesn't change files. |

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](#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](/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.

```json
{
  "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.