Local demo and CLI access
This guide gets a local Farmslot gateway running, opens Command Center, and shows how terminals or agents can talk to the same gateway through the farmslot CLI.
Start the local demo
From the repository root:
bash scripts/dev.sh
Open http://localhost:7777. The local demo pool exposes demo-ff-1, a scripted-runner validation path that is safe to inspect and dispatch against while learning the product.
Command Center is the primary operator surface: use it to see the fleet, inspect slot readiness, watch runs, review artifacts, and steer work.
Use the CLI against the gateway
The farmslot CLI is for terminals, scripts, and agent shells. It speaks to the gateway over WebSocket and can target any reachable gateway.
When running from this repo before package publication, use the workspace script:
yarn workspace @farmslot/cli farmslot fleet status
yarn workspace @farmslot/cli farmslot slot check demo-ff-1
Once installed as a binary, the same calls are:
farmslot fleet status
farmslot slot check demo-ff-1
Target another gateway with --url:
farmslot --url ws://host:7777 fleet status
Use --json for machine-readable output.
Raw gateway RPC
Agents and scripts can call protocol methods directly:
farmslot rpc fleet.status '{}'
farmslot rpc gateway.status '{}'
There is no runtime discovery method, so look the method set up ahead of time: see Gateway API capability surface for the curated API overview, including safety tiers.
Slot lifecycle commands
Slot lifecycle values are ready, busy, held, manual and disabled.
Preparation, dispatch, work and release are phases within that lifecycle; they
are not additional slot states. A held slot can monitor a PR or defer cleanup.
Manual and disabled slots do not accept automatic dispatch.
| CLI command | Purpose |
|---|---|
farmslot fleet status | Fleet-wide overview of machines, slots, health, and current runs. |
farmslot slot check <id> | Read-only deep health check for one slot. |
farmslot slot prepare <id> | Sync fixtures, checkout branch, and run project preflight. |
farmslot dispatch preview | Preview slot/project fit before creating a run. |
farmslot run create ... | Create a supervised run from a Jira/GitHub ref or an existing TASK.md. |
farmslot slot release <id> | Collect artifacts, clean up, and optionally re-prepare with --keep-warm. |
farmslot rpc <method> | Raw gateway escape hatch for protocol methods and agent integrations. |
Create runs from either source:
farmslot run create --project example-project --flow-type dev \
--ticket https://github.com/example/project/issues/123 \
--slot example-slot-1
farmslot run create --task projects/example-project/tasks/dev/example/TASK.md \
--slot example-slot-1
About the shell scripts
The scripts/*.sh lifecycle commands are lower-level building blocks used by the gateway, CLI, and local debugging. They remain useful for development and recovery, but they are not the public getting-started surface.
Recover a worker
farmslot run get <runId> shows recovery hints, including the pending decision and its resolution commands. farmslot run resume <runId> also handles a blocked native worker whose handoff decision supports saved-conversation recovery.
If the saved worker conversation was resumed outside the gateway, use farmslot run adopt <runId> --tmux <session>. Adoption verifies its process and conversation identity, refuses another live owner, and resumes task monitoring. It does not create or restart that session.
For run create --task, update the CLI on every node before upgrading the gateway. New clients send paths resolved from the caller's working directory. The updated gateway rejects new relative paths and tells older clients to upgrade. Historical runs remain readable.