FirstMate: agent crews, durable evidence and delivery authority
Deploying FirstMate: code roots, private homes and runtime backends
Plan a local agent operating environment rather than a web-server deployment, with separate private state, deliberate credentials and versioned updates.
What you will learn
- This deployment is an operating environment
- Separate capabilities and private state
- Upgrade and recover without erasing evidence
Before you start
- Git worktrees and pull-request basics
- Understanding of terminal agents and credential scope
Define a delivery contract and inspect state and authority evidence without claiming untested runtime guarantees.
Key takeaways
- A code checkout and a private operating home serve different purposes.
- Backend maturity differs at the pinned revision.
- Remote route failure is not permission to create a local replacement.
This deployment is an operating environment
There is no application HTTP port to expose merely because you cloned FirstMate. The documented baseline is macOS or Linux, Git, authenticated GitHub CLI and a supported agent harness with its backend dependencies. The reference backend is tmux. Do not infer native Windows support from the presence of portable-looking shell commands.
The tracked code root contains shared instructions and scripts. Each effective FM_HOME contains private operating directories. Configuration assigns durable fleet records to data, runtime coordination to state, local operating choices to config and project clones to projects. Backing up code alone therefore does not preserve the fleet’s operational history.
Separate capabilities and private state
Treat the effective home as sensitive: briefs, reports, task metadata and optional Relay artifacts can reveal project details. Exclude private state from public repositories and apply your own access and retention policy. The documented gitignored layout reduces accidental tracking; it is not encryption or a complete backup strategy.
Choose the backend explicitly for a trial and document the selected identity. The architecture describes tmux as reference, Herdr with a required CI lane, and zellij, Orca and cmux as experimental task-spawn adapters. Those upstream coverage levels are not interchangeable, and Codex App is not a selectable runtime backend at this revision.
Upgrade and recover without erasing evidence
Record the code revision together with the effective home and backend. Before an upgrade, preserve a recoverable snapshot of your private state according to local policy and inspect the change while work is quiescent. Do not delete a home or worktree merely to clear a confusing status; task ownership and unlanded work may still depend on it.
Optional secondmates use isolated homes locally or on an SSH-reachable host. An unavailable remote route must not be silently replaced by a local home. Start with local operation and test remote failure separately. No remote provisioning, rollback or backup restore was executed for this article.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Document platform, harness and backend before installation.
- 2
Identify the effective home and protect its private state.
- 3
Record revision and recovery evidence before upgrades.
- 4
Test remote operation separately from the local baseline.
Copy-ready example
{
"planningRecord": true,
"sourceRevision": "b182d0f908b78d08c7ccb8dce3775bdca8c5d657",
"effectiveHome": "choose a private path",
"backend": "tmux",
"remoteSecondmatesEnabled": false,
"restoreTested": false
}Frequently asked questions
Which service port should I expose?
This distro does not itself require a web-server deployment; assess any optional integration separately.
Does gitignore protect confidential reports?
It helps prevent tracking but does not encrypt files or control access to the machine.
Sources
- FirstMate / README.mdSource checked 2026-09-14
- FirstMate / docs/configuration.mdSource checked 2026-09-14
- FirstMate / docs/architecture.mdSource checked 2026-09-14