Skip to content

Factory: local setup

This page covers the local Factory path for Linear Agents. Most users only need to create their local agents and run workers. Relay setup is shared infrastructure and is only needed when the relay has not been deployed yet.

For architecture background, see Factory.

Prerequisites

  • Repo bootstrapped with backend dependencies (./bootstrap.py from the repo root).
  • gcloud authenticated against the inboundx GCP project.
  • gh authenticated against inboundx/inboundx.
  • claude and/or codex installed. just add-agent checks the selected engine and can launch the login flow if needed.

Shared Relay Setup

Skip this section if rose-factory-relay already exists. Relay setup is for the person maintaining the shared hosted relay.

Deploy or redeploy the relay:

cd factory
just deploy

just deploy builds factory/relay/Dockerfile with Cloud Build and deploys the rose-factory-relay Cloud Run service.

The first deploy assumes the shared relay infrastructure already exists:

  • GCS bucket for relay events.
  • Secret Manager config secret rose-factory-relay-config.
  • Cloud Run runtime service account can read the config secret.
  • Cloud Run runtime service account can read/write the relay bucket.

The relay is public because Linear webhooks cannot use Google OIDC. Auth is handled by the app: Linear webhook signatures for /webhooks/linear, and worker bearer tokens for /events, /activity, and /issue-state.

Create Your Agents

Do this on each laptop that should run Factory agents.

Create each Linear Agent this laptop should run:

cd factory
just add-agent

just add-agent is the source of truth for declaring an agent. It asks for the owner, engine, agent id, and Linear OAuth app credentials. It then wires the relay, stores secrets, installs the Linear app, writes ~/rose-factory/relay.env, and appends the agent_session entry to ~/rose-factory/agents.yaml.

When the wizard opens the Linear app creation page, use:

Setting Value
Webhooks On
App events Agent session events only
Webhook URL https://<relay-url>/webhooks/linear
Redirect URI https://<relay-url>/oauth/callback

Repeat just add-agent for every agent identity you want on this machine.

Run Workers

Run all local Linear Agent workers with one command:

cd factory
just run-all

just run-all reads ~/rose-factory/agents.yaml, sources ~/rose-factory/relay.env, long-polls the relay, and launches the configured local engine for each queued issue.

If the registry still contains legacy api_key agents, remove them or run only one Linear Agent worker:

cd factory
just run-agents <agent-id>

Use From Linear

  1. Open a Linear issue.
  2. Assign it to the Linear Agent app user, or @-mention the app user.
  3. The relay queues the session event.
  4. The local worker creates or reuses a worktree under ~/rose-factory/workspaces/<agent-id>/<ISSUE-ID>.
  5. The local engine runs, commits, pushes, opens a PR targeting develop, and posts the result back to Linear.

Follow-up instructions go through the same Linear Agent session or another @-mention. The worker reruns the issue workspace with the new instruction.

Local Files

Path Purpose
~/rose-factory/agents.yaml Per-machine agent registry
~/rose-factory/relay.env Local relay worker token
~/rose-factory/cursors/ Relay event cursors
~/rose-factory/workspaces/ Per-issue git worktrees
.context/factory-orchestrator-state.json Local orchestrator processed state

Troubleshooting

Symptom Fix
Relay ... not found ... deploy it first from just add-agent Run cd factory && just deploy, then retry just add-agent.
Cannot reach the relay Check gcloud auth list, GCP_PROJECT_ID, RELAY_REGION, and RELAY_SERVICE.
FACTORY_RELAY_WORKER_TOKEN missing Re-run just add-agent; it writes ~/rose-factory/relay.env.
Assignment works but no local run starts Start just run-all and confirm the agent id exists in ~/rose-factory/agents.yaml.
Engine fails immediately Sign in locally with codex login or claude auth login.