First-time Fabric setup
Follow these steps on the Mac that will run your agents. You do not need the Fabric source repository to use the installer.
Reference
1. Get the prerequisites
Ask your Fabric maintainer for the latest approved installer ZIP, the signed .forge-agent package you will use, and an optional setup bundle. These are three different files.
| Requirement | What you need |
|---|---|
| Mac | Apple Silicon, macOS 13 or later for Executor; macOS 14 or later for the recommended Local AI setup. |
| Game files | Access to your team’s repositories. Offers preparation also needs a real gotm_livedata Git checkout. |
| Service access | Your own Jira/Perforce/Git credentials, required network or VPN access, and permissions to the actual ticket and assets. |
| Native tools | Photoshop with the Fabric UXP provider for Photoshop stages; the correct Unity project and MCP bridge for Unity stages. |
| AI | Disk space and time for model downloads, or a team-approved cloud provider. The setup assistant reports available options. |
Reference
2. Install and open
- Close Executor and Studio when no jobs are running. Extract the installer ZIP in Finder.
- Open Fabric Installer.app, check its version, follow the prompts, and wait for completion. Do not modify its embedded payload.
- Open Fabric.app (Fabric) from the Applications folder selected during installation. The default user folder is
~/Applications(Finder → Go → Go to Folder). - Use the address opened by Executor. Check Settings → General → Dashboard → Port if needed; the port can differ across Macs. Wait for Backend readiness.
- Confirm the installed version in Settings → General → About Fabric. If installation fails verification, get a replacement installer; see installer recovery.
Reference
3. Complete the setup assistant
The installer checks Homebrew and the Perforce p4 CLI, then imports only the existing non-secret P4 port, user and client defaults. Credentials remain in Perforce. It also installs hardware-matched routing, code, vision and embedding models when Local AI is selected. Open Settings → General → Open setup assistant to review readiness and repair any download or tool setup that could not complete.
Reference
4. Import team setup, if provided
- Open Settings → General → Setup and transfer → Import setup bundle. Choose the team’s setup ZIP, not the installer ZIP.
- Review the preview, keep existing files unless replacement is intended, and check only the paths that are correct on this Mac.
- Import, then select the imported draft under Environment profile and click Apply when ready. Imported profiles do not activate automatically.
- Enter your own connector credentials. Setup bundles exclude secrets, private conversations, run history and the built RAG index. See the full transfer guide.
Reference
5. Set the project folders
Open Settings → General → Paths. Use Browse to choose existing local folders. The installer does not clone game repositories.
| Field | Select |
|---|---|
| Unity project | The project folder containing Assets and ProjectSettings, typically the game’s client folder. |
| Git worktree | The game checkout used by the configured workflow. It is distinct from the Live-data repository. |
| Live-data repository | The actual root of gotm_livedata, for example ~/Documents/GitHub/gotm_livedata. An empty folder or a subfolder is not sufficient. |
| Development code root | The code folder used for code context and skill discovery, usually the game’s client folder. |
| Perforce workspace | The exact root reported by your selected P4 client, not simply the parent folder containing all workspaces. |
Click Save paths. If a restart is pending, wait for idle, use the Backend panel’s Restart, and wait for Ready. All path fields explained.
Reference
6. Connect the services your agent needs
Open Settings → Connectors. Save credentials, test access, and open the native applications required by the selected agent. Resolve its required warnings before running. Optional unused connectors can stay unconfigured.
For Google Sheets, import a registered Desktop OAuth client JSON before signing in. A Google password cannot enable the disabled button. Follow each connector’s setup steps.
Reference
7. Import the agent and build knowledge
- Open Pipeline → Import agent and select the approved signed
.forge-agentfile. Review the package and its trust/compatibility result. - Imported agents require the Executor’s admission checks. A valid independently certified package with satisfied dependencies can be ready for manual runs without a second commissioning step. Otherwise resolve the missing certification/commissioning with the maintainer. Importing does not approve external effects.
- In Settings → Knowledge, review sources and click Build knowledge index or Rebuild knowledge index. Hybrid deployments use Refresh governed index. Check the result, freshness and required-source access.
- Run Settings → General → Run health check. Resolve failures relevant to this agent.
Reference
8. Run one ticket
- Select the intended agent and enter the Jira ticket plus all required inputs. Faction workflows may require an explicit faction/member manifest.
- Leave Commit & push off for the first preparation run. Preparation can still create local files and use Photoshop; it is not a read-only test.
- Click Run, follow stages, and inspect the outputs or requested review. Use the exact approval controls for later delivery.
- If the job fails, read its diagnostics before retrying. A pending PR merge or review is a checkpoint, not completed delivery. Run and recovery guide.
Reference
You are ready for a first supervised run when…
The backend is ready, paths point to this Mac’s real repositories, the required connectors pass, knowledge is usable, and the selected agent has the required admission checks and inputs. Keep a reviewer available for the first run.