Workstreams Quickstart

Before you start

• Use a Pro, Plus, Max, or Teams plan. Workstreams is in beta and not yet available on Business or Enterprise.
• Sign in to the Factory App.
• Set up an environment with your repository, so the workstream can run on cloud computers. Running on this computer (Local) instead requires the desktop app.
• Decide where agents may run. When the orchestrator runs on an environment, each agent gets its own fresh computer from it, as long as Remote delegation is on (the default). To let agents use other environments or your own machines, set up Workstream Defaults first; see Machines.

Step 1: create the workstream

In the sidebar, click New Workstream (the + next to Workstreams) to open the New Workstream dialog.

1. 1
   Name it after the goal

   Give the workstream a name that states the goal, for example "Migrate the billing service to the new payments API." The name shows in the sidebar and above the workstream, and the orchestrator reads it as context. You can also pick a symbol for it.

2. 2
   Choose the orchestrator machine

   Under Orchestrator machine, choose an environment. The workstream gets a fresh cloud computer, so it keeps working after you close your laptop. You can also choose one of your Droid Computers, or Local to run on this computer (desktop app only). For Local or an existing computer, also choose the Working directory and Branch, and optionally Run in a worktree.

3. 3
   Check where agents can run

   Agent machines summarizes the machines agents may use, based on your Workstream Defaults.

4. 4
   Start

   Click Start. The app sets up the machine and starts the orchestrator.

Step 2: give the orchestrator its first task

The orchestrator doesn't start on its own. It waits for your first message. Describe the goal, the constraints, and what done looks like:

Migrate the REST handlers in services/api from Express to Fastify. Keep every route's
behavior the same and the test suite green. Open one PR per service. Ask me before
changing any public response shape.

A good first message covers:

• The outcome you want and how you'll judge it.
• Constraints, such as files to leave alone, APIs that must not change, or a deadline.
• How to verify the work, such as test commands or a script that runs the app.
• Decisions you want to make yourself.

The orchestrator then splits the work and starts agents, and keeps you posted as it goes.

Step 3: follow the agents

Open the Agents tab in the right pane. Agents are grouped by state:

• Waiting on you: the agent has a question or needs approval to run a tool.
• Working: the agent is in the middle of a turn.
• Idle: the agent finished its turn and is waiting for more work.

Click an agent to open its session in a tab. You can read what it's doing, answer its questions, approve tool calls, and message it directly. To change direction for the whole workstream, message the orchestrator instead.

Step 4: review the results

• The PRs tab lists every pull request the agents open, with CI status. See Pull requests.
• The Files tab shows the workstream's shared folder: plans, notes, findings, and other documents the agents saved. See Shared folder.

When you're ready for the next piece of work, tell the orchestrator. The same workstream keeps going, and the orchestrator reuses agents that already know the code.