Skip to main content
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. Sign in to the Factory CLI and check your setup:
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). 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:
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:
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:
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:

​
If setup is incomplete

Add one to the same workspace.
Check its name in repos and the GitHub App’s repository access.
Check the provider connection and the board reference, then follow the fix push reports.
Check the column’s exact spelling. Remove mappings for columns you don’t have.
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.
Preview factory pull, pull the latest version, and review it before you push again.
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.