---
title: Getting started
description: Deploy Foreman against your repository with the Vercel button or the CLI, run it locally in the dev TUI, and validate changes before shipping.
type: guide
summary: From zero to a deployed factory working your repository.
related:
  - /docs/configuration
  - /docs/intake
  - /docs/troubleshooting
---

# Getting started



Deploy Foreman against your repository and label an issue to see the whole line run. Deploying from the Vercel dashboard sets up everything for you; the manual path takes about six commands.

## Before you begin

Foreman runs on Vercel and works on a single GitHub repository, so set up three things first.

1. Create a Vercel account if you do not already have one. Beyond hosting the agent, the factory uses Vercel Connect for GitHub and Linear auth, Vercel Blob to store the factory brain and user preferences, and Vercel Sandbox for the station checkouts.
2. Choose the repository you want the factory to work on. Its `owner/repo` becomes the value of `FACTORY_REPO`.
3. Make sure the GitHub App ends up installed on that repository, with write access to contents, issues, and pull requests. Vercel Connect creates the app for you during setup, so you install it once the connector exists rather than beforehand.

## Deploy with the button

<a href="https://vercel.com/new/clone?project-name=eve-software-factory&repository-name=eve-software-factory-template&repository-url=https%3A%2F%2Fgithub.com%2Fvercel-labs%2Feve-software-factory-template&env=FACTORY_REPO,FACTORY_LABEL&envDefaults=%7B%22FACTORY_LABEL%22%3A%22factory%22%7D&envDescription=FACTORY_REPO%20is%20the%20owner%2Frepo%20the%20factory%20works%20on.%20FACTORY_LABEL%20is%20the%20issue%20label%20that%20hands%20an%20issue%20to%20the%20factory%3B%20the%20default%20label%20is%20fine.&connect=%5B%7B%22type%22%3A%22github%22%2C%22env%22%3A%22GITHUB_CONNECTOR%22%2C%22triggers%22%3Atrue%2C%22triggerPath%22%3A%22%2Feve%2Fv1%2Fgithub%22%7D%2C%7B%22type%22%3A%22linear%22%2C%22env%22%3A%22LINEAR_CONNECTOR%22%2C%22triggers%22%3Atrue%2C%22triggerPath%22%3A%22%2Feve%2Fv1%2Flinear%22%7D%5D&stores=%5B%7B%22type%22%3A%22blob%22%2C%22access%22%3A%22public%22%7D%5D" rel="noreferrer" target="_blank">
  <img alt="Deploy on Vercel" height="32" src="https://vercel.com/button" width="103" />
</a>

Clicking Deploy opens a Vercel setup flow that creates the resources below, then asks you for two values.

| Creates                                                                            | What it does                                                                                             |
| ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| [Vercel Connect](https://vercel.com/docs/connect) connectors for GitHub and Linear | Mint short-lived provider tokens, and forward verified webhooks to `/eve/v1/github` and `/eve/v1/linear` |
| Vercel Blob store                                                                  | Holds the factory brain and user preferences                                                             |

Each connector has a UID, a string like `github/foreman-agent`. Vercel stores those in `GITHUB_CONNECTOR` and `LINEAR_CONNECTOR`, which exist only to hold them: the code reads each variable to name the connector it wants a token from.

The two prompts are `FACTORY_REPO` and `FACTORY_LABEL`, where the default label of `factory` is fine.

## Deploy manually

<Steps>
  <Step>
    ### Clone and install

    ```bash
    git clone https://github.com/vercel-labs/eve-software-factory-template.git my-factory
    cd my-factory
    pnpm install
    ```
  </Step>

  <Step>
    ### Create and link the Vercel project

    ```bash
    vercel link
    ```
  </Step>

  <Step>
    ### Create the GitHub connector

    Subscribe to `issues` for label intake, `issue_comment` and `pull_request_review_comment` for mentions, `pull_request` for summary comments, and `check_suite` for red-CI fixes during registration.

    ```bash
    vercel connect create github --triggers
    vercel connect attach <github-uid> --triggers --trigger-path /eve/v1/github --yes
    ```
  </Step>

  <Step>
    ### Create the Linear connector

    Subscribe to the `AgentSessionEvent` webhook category during registration.

    ```bash
    vercel connect create linear --triggers
    vercel connect attach <linear-uid> --triggers --trigger-path /eve/v1/linear --yes
    ```
  </Step>

  <Step>
    ### Set the environment variables

    Use the connector UIDs printed by the previous two steps, plus your target repository as `owner/repo`.

    ```bash
    vercel env add GITHUB_CONNECTOR
    vercel env add LINEAR_CONNECTOR
    vercel env add FACTORY_REPO
    ```
  </Step>

  <Step>
    ### Create the Blob store and deploy

    `eve deploy` wraps `vercel deploy --prod`. Use it rather than the raw command, which cannot auto-detect the eve framework.

    ```bash
    vercel blob create-store factory-store --access public --yes
    eve deploy
    ```
  </Step>
</Steps>

Once the deployment is live, label an issue `factory` or mention `@Foreman` on one. See [how work arrives](/docs/intake) for every entry point.

## Deploy with a coding agent

Paste this prompt into a coding agent and it handles the deployment end to end, asking you for the values only you know. The manual commands above are the same ones it follows.

<CopyPrompt
  text={`Deploy the eve Software Factory template (vercel-labs/eve-software-factory-template) against my repository. Clone it, then follow the Manual Setup section of its README.md as written rather than inventing commands.

1. Ask me for the target repository as owner/repo, which becomes FACTORY_REPO.
2. Clone the template, install dependencies, and create and link a Vercel project.
3. Create the GitHub and Linear connectors with triggers at /eve/v1/github and /eve/v1/linear, and set their UIDs as GITHUB_CONNECTOR and LINEAR_CONNECTOR.
4. Add FACTORY_REPO to the Vercel environment and create the Blob store.
5. Deploy with eve deploy.

Before finishing, confirm the GitHub App is installed on the target repository with write access to contents, issues, and pull requests. If a command fails, show me the output and stop. Once the deployment is live, tell me to label a test issue with the factory label and watch for a draft PR.`}
>
  Deploy the eve Software Factory template (`vercel-labs/eve-software-factory-template`) against my repository. Clone it, then follow the Manual Setup section of its `README.md` as written rather than inventing commands.

  1. Ask me for the target repository as `owner/repo`, which becomes `FACTORY_REPO`.
  2. Clone the template, install dependencies, and create and link a Vercel project.
  3. Create the GitHub and Linear connectors with triggers at `/eve/v1/github` and `/eve/v1/linear`, and set their UIDs as `GITHUB_CONNECTOR` and `LINEAR_CONNECTOR`.
  4. Add `FACTORY_REPO` to the Vercel environment and create the Blob store.
  5. Deploy with `eve deploy`.

  Before finishing, confirm the GitHub App is installed on the target repository with write access to contents, issues, and pull requests. If a command fails, show me the output and stop. Once the deployment is live, tell me to label a test issue with the `factory` label and watch for a draft PR.
</CopyPrompt>

## Configure

Two variables matter at setup time. The [configuration](/docs/configuration) page has the full table.

`FACTORY_REPO` is required. It is the `owner/repo` the factory works on, read at module load and validated, so a missing or malformed value fails the build rather than a session.

`FACTORY_SETUP_COMMAND` is optional, for example `pnpm install`. It runs inside the station sandboxes' clone once per template build, so sessions start with your repository's checks already runnable. A failure there fails the build, not a session.

Vercel Blob and the AI Gateway authenticate requests through the project's OIDC token.

## Run locally

<Steps>
  <Step>
    ### Link and pull the environment

    `vercel env pull` supplies a short-lived OIDC token, which the Connect credentials and the station sandboxes both need.

    ```bash
    vercel link
    vercel env pull
    ```
  </Step>

  <Step>
    ### Start the TUI

    Run `/model` once inside the TUI to link a model provider.

    ```bash
    pnpm dev
    ```
  </Step>

  <Step>
    ### Hand it a work item

    Try something like "users report the password reset email arrives twice, fix it". Watch the four stations fire in order, ending in a draft pull request on `FACTORY_REPO`.
  </Step>
</Steps>

The dev principal is deliberately untrusted, so GitHub writes park on approval cards in the TUI. Approving them yourself doubles as a demo of the human gate. The webhook surfaces, meaning mentions, the `factory` label, and Linear sessions, run against a deployment rather than the local TUI.

## Verify before shipping

Run `pnpm validate` before deploying any change. It bundles lint, typecheck, and eve discovery diagnostics, and all three must report zero errors and zero warnings.

```bash
pnpm validate
```

The eval suite is optional but worth running when you touch routing or policy.

```bash
pnpm eval --tag fast              # the default loop: smoke + safety, cheap
pnpm eval pipeline/full-pipeline  # opt-in: runs the whole line and pushes a real branch
```

<Callout type="warn" title="Costs real tokens">
  Evals call real models, and `pipeline/full-pipeline` pushes a real branch. Point `FACTORY_REPO` at a scratch repository before running it. The [evals](/docs/evals) page covers the whole suite.
</Callout>

## Next steps

<Cards>
  <Card href="/docs/intake" title="How work arrives" description="Every way work reaches the factory, and what each surface trusts." />

  <Card href="/docs/configuration" title="Configuration" description="The full environment variable reference, models, and session budget." />

  <Card href="/docs/troubleshooting" title="Troubleshooting" description="What to check when a label does nothing or the build fails at discovery." />
</Cards>


---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)