> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Factory on Mutagent Cloud

> Connect GitHub, push your configuration and run stages in cloud sandboxes.

> [!NOTE]
>
> **Early Access.** Commands and behavior can change between releases.

Mutagent Cloud runs Factory stages in sandboxes. Agents work on GitHub through the **GitHub App**:
they push branches, open pull requests and post reviews with the App's access, not with a personal
token in `factory.yaml`.

**1. Prepare the workspace**

Factories and model providers belong to a [workspace](https://docs.mutagent.io/get-started/accounts.md). Sign in to the
Factory CLI and check your setup:

```bash theme={null}
architech factory login --json
architech factory status --json
```

Open the sign-in URL the CLI prints and approve it. To pick a workspace, add
`--workspace <workspace-id>` to Factory commands.

Add an LLM provider to that workspace ([provider setup](https://docs.mutagent.io/helix/cloud/setup.md)). The Factory runs on
your model credentials. Without a provider, work can pause with `NO_PROVIDER_CONFIGURED`. Your
local shell credentials are not copied to Cloud.

**2. Connect GitHub once**

Connect GitHub in Cloud and give the App access to the repositories the Factory will use. This
command opens the consent flow:

```bash theme={null}
architech factory integrations connect github --wait --json
```

Open the printed URL. If GitHub is already connected in the workspace, check `status` before you
start another consent flow. If permissions need a refresh, follow the fix the CLI returns. For a
Linear board, run `integrations connect linear --wait`; you still need GitHub for the code.

**3. Push the file**

Run these from the repository that holds `.architech/factory/factory.yaml`:

```bash theme={null}
architech factory push --dry-run --json
architech factory push --json
architech factory status --json
```

> [!NOTE]
>
> Push reports `linked`, `board` and `drift`, so you see what's ready and what needs work. It
> doesn't link repositories or bind the board. A mapped column that doesn't exist gives a warning
> with a fix; it doesn't fail the whole setup.

Push doesn't give the App new permissions. If it can't reach a repository, update the GitHub
connection and push again. Read the warnings even when push succeeds.

Follow the setup steps push returns. If it says the board is not bound, run this once. It reads
the board from the pushed file:

```bash theme={null}
architech factory board bind <factory-id> --json
```

A real push changes `mode: local` to `mode: cloud`, and adds
your installed release's framework pin if the file has none. In a normal Git checkout, push commits the changed file.
Check `committed` and the notices: on a detached HEAD, or if the commit fails, the file can stay
uncommitted even though Cloud accepted the push. Pushing sets up the Factory; turning it on is a
separate step:

```bash theme={null}
architech factory enable <factory-id> --json
```

## If setup is incomplete

> **No model provider**
>
> Add one to the same workspace.

> **A repository cannot be linked**
>
> Check its name in `repos` and the GitHub App's repository access.

> **Board not bound**
>
> Check the provider connection and the board reference, then follow the fix push reports.

> **Missing mapped column**
>
> Check the column's exact spelling. Remove mappings for columns you don't have.

> **No board pickup**
>
> Check that the Factory is enabled, that the issue has every pickup label (`factory:pickup` by default) and no hold label, and that it isn't in `triage`.

> **A stale configuration**
>
> Preview `factory pull`, pull the latest version, and review it before you push again.

> [!WARNING]
>
> Cloud sandboxes check out your repository without submodule contents, and can't publish a
> submodule pointer change as a pull request. A repository with submodules still works for changes
> outside them.

Next: [watch runs, approve gates and answer questions](https://docs.mutagent.io/factory/operating.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.