# What Are Secondmates in Firstmate and How They Differ from Crewmates > Understand Secondmates in Firstmate, persistent isolated homes with unique projects and workers, and how they differ from ephemeral crewmates designed for single tasks. Learn more now. - Repository: [Kun Chen/firstmate](https://github.com/kunchenguid/firstmate) - Tags: deep-dive - Published: 2026-08-13 --- **Secondmates in Firstmate are persistent, isolated homes that maintain their own projects, backlog, and workers, whereas crewmates are ephemeral agents spawned for a single task and terminated immediately after completion.** Firstmate is an open-source execution framework that manages distributed work through a hierarchical agent model. Understanding the distinction between secondmates and crewmates is essential for architecting scalable deployments, as these two agent types handle fundamentally different lifecycle and isolation requirements according to the kunchenguid/firstmate source code. ## Defining Secondmates and Crewmates ### What Are Secondmates? Secondmates are durable, isolated environments that function as secondary Firstmate homes. According to the architecture documentation in [`docs/architecture.md`](https://github.com/kunchenguid/firstmate/blob/main/docs/architecture.md), a secondmate maintains its own `projects/` directory tree, independent [`data/backlog.md`](https://github.com/kunchenguid/firstmate/blob/main/data/backlog.md), and dedicated worker processes. They are created once using [`bin/fm-home-seed.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-home-seed.sh) (or [`bin/fm-remote-home-seed.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-remote-home-seed.sh) for remote variants) and persist across multiple task executions until explicitly torn down with [`bin/fm-teardown.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-teardown.sh). ### What Are Crewmates? Crewmates are transient execution agents designed for single-task operations. As implemented in [`tests/fm-turnend-guard.test.sh`](https://github.com/kunchenguid/firstmate/blob/main/tests/fm-turnend-guard.test.sh), crewmates are instantiated via `make_crewmate_worktree_dir` and exist only for the duration of a specific ship or scout operation. They share the primary home's configuration and project registry, lacking their own backlog or isolated storage. ## Key Architectural Differences The execution model distinguishes these agents across four critical dimensions: **Lifecycle Duration** Secondmates follow a persistent lifecycle model defined in [`bin/fm-home-seed.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-home-seed.sh) and [`bin/fm-teardown.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-teardown.sh), remaining active across many routing decisions. Crewmates are spawned on-demand by [`bin/fm-spawn.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-spawn.sh) (without the `--secondmate` flag) and automatically terminate when their assigned task completes. **Isolation Scope** A secondmate owns a complete Firstmate home environment, including its own `projects/` tree and [`data/backlog.md`](https://github.com/kunchenguid/firstmate/blob/main/data/backlog.md). This isolation allows secondmates to function as independent fleets. Crewmates operate within the primary home's workspace, directly observing the primary's wake queue without intermediate routing layers. **Supervision Model** Supervision of secondmates is hierarchical: the primary home manages the secondmate's health, but the secondmate runs its own internal supervision loop. In contrast, crewmates are supervised entirely by the primary home, with their status lines absorbed directly into the primary's wake queue as ordinary events. **Status Signal Handling** As verified in [`tests/fm-watch-triage.test.sh`](https://github.com/kunchenguid/firstmate/blob/main/tests/fm-watch-triage.test.sh), secondmate status streams are treated as routed-reply channels and are never absorbed as normal crewmate status signals. This distinction ensures that the primary home can distinguish between internal task completion (crewmate) and fleet-level health reports (secondmate). ## Working with Secondmates ### Creating Local Secondmates To establish a persistent local secondmate, use the seeding script. This registers the secondmate in [`data/secondmates.md`](https://github.com/kunchenguid/firstmate/blob/main/data/secondmates.md) and initializes its isolated environment: ```bash # Create a persistent local secondmate with ID 'sm1' bin/fm-home-seed.sh sm1 ``` ### Remote Secondmate Deployment Secondmates support remote deployment via SSH, placing a complete Firstmate home on a separate host. The primary instance retains routing and supervision control while the remote home maintains its own projects and workers as documented in [`docs/remote-secondmates.md`](https://github.com/kunchenguid/firstmate/blob/main/docs/remote-secondmates.md): ```bash # Seed a remote secondmate (ID: rsm) on an SSH-accessible host bin/fm-remote-home-seed.sh rsm my-ssh-alias \ /remote/firstmate/root /remote/secondmate/home \ projectA=https://example.com/projectA.git projectB ``` ### Launching Tasks and Teardown Tasks are dispatched to secondmates using the `--secondmate` flag with [`bin/fm-spawn.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-spawn.sh). When retiring a secondmate, use the guarded teardown script to ensure proper cleanup: ```bash # Spawn a crewmate inside the secondmate home to execute work bin/fm-spawn.sh sm1 --secondmate # Gracefully retire a secondmate (local or remote) bin/fm-teardown.sh sm1 ``` ## Crewmate Execution Patterns Crewmates are spawned for immediate task execution without persistent state. The spawn script creates these ephemeral agents within the primary home's context: ```bash # Spawn a standard crewmate for a single task bin/fm-spawn.sh -- crewmate-task-id ``` Unlike secondmates, crewmates created via [`bin/fm-spawn.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-spawn.sh) without the `--secondmate` flag cannot be targeted for remote execution and do not require explicit teardown, as they terminate automatically upon task completion. ## Summary - **Secondmates** are persistent, isolated Firstmate homes defined in [`docs/remote-secondmates.md`](https://github.com/kunchenguid/firstmate/blob/main/docs/remote-secondmates.md) that maintain their own `projects/` directories, [`data/backlog.md`](https://github.com/kunchenguid/firstmate/blob/main/data/backlog.md), and worker fleets across multiple task cycles. - **Crewmates** are ephemeral agents created by [`bin/fm-spawn.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-spawn.sh) for single-task execution, sharing the primary home's configuration and terminating automatically after completion. - Secondmates support both local and remote deployment via [`bin/fm-home-seed.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-home-seed.sh) and [`bin/fm-remote-home-seed.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-remote-home-seed.sh), while crewmates execute only within their target home environment. - Status signals from secondmates are routed separately from crewmate events, as enforced by the supervision logic in [`tests/fm-watch-triage.test.sh`](https://github.com/kunchenguid/firstmate/blob/main/tests/fm-watch-triage.test.sh). ## Frequently Asked Questions ### Can a secondmate run on a different host than the primary Firstmate instance? Yes. Secondmates support remote deployment through [`bin/fm-remote-home-seed.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-remote-home-seed.sh), which provisions a complete Firstmate home on an SSH-reachable host. The primary instance maintains routing and supervision responsibilities while the remote secondmate retains its own isolated projects, backlog, and workers. ### Why would I use a secondmate instead of a regular crewmate? Use a secondmate when you need persistent isolation for long-running projects or distributed fleets. Secondmates maintain state across tasks via their own [`data/backlog.md`](https://github.com/kunchenguid/firstmate/blob/main/data/backlog.md) and `projects/` tree, making them suitable for secondary fleets. Crewmates are appropriate for short-lived, stateless tasks that do not require persistent storage or cross-task continuity. ### How does Firstmate prevent secondmate status signals from interfering with crewmate supervision? The supervision layer treats secondmate status streams as routed-reply channels rather than ordinary wake events. As tested in [`tests/fm-watch-triage.test.sh`](https://github.com/kunchenguid/firstmate/blob/main/tests/fm-watch-triage.test.sh), the classification logic explicitly prevents absorption of secondmate status signals into the primary crewmate supervision queue, ensuring clean separation between fleet-level health reports and task-level status updates. ### Do crewmates require manual teardown like secondmates? No. Crewmates are ephemeral by design and terminate automatically upon task completion. Secondmates require explicit retirement via [`bin/fm-teardown.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-teardown.sh) because they persist as autonomous homes with their own supervision loops and state management.