PhyAgentOS — Fleet Mode

Fleet Topology

Fleet mode introduces a shared workspace that the Agent operates on, plus one per-robot workspace for each Watchdog. The Critic validates actions against the target robot's EMBODIED.md.

flowchart TB
    subgraph Shared["Shared Workspace"]
        ENV["ENVIRONMENT.md"]
        ROBOTS["ROBOTS.md"]
        LESSONS["LESSONS.md"]
        TASK["TASK.md"]
        ORCH["ORCHESTRATOR.md"]
    end
    subgraph Robot1["Robot A Workspace"]
        ACT1["ACTION.md"]
        EMB1["EMBODIED.md"]
    end
    subgraph Robot2["Robot B Workspace"]
        ACT2["ACTION.md"]
        EMB2["EMBODIED.md"]
    end
    subgraph Robot3["Robot C Workspace"]
        ACT3["ACTION.md"]
        EMB3["EMBODIED.md"]
    end
    Shared --> Robot1
    Shared --> Robot2
    Shared --> Robot3

The Agent reads and writes to the shared workspace. Each Watchdog monitors its own robot workspace. The Critic checks every action against that target robot's EMBODIED.md before the action lands in ACTION.md.

Configuration

Enable fleet mode in config.json by setting embodiments.mode to "fleet" and listing each robot instance with its driver and workspace path.

{
  "embodiments": {
    "mode": "fleet",
    "shared_workspace": "~/.PhyAgentOS/fleet/shared",
    "instances": [
      {
        "robot_id": "go2_edu_001",
        "driver": "go2_edu",
        "workspace": "~/.PhyAgentOS/fleet/robot_go2"
      },
      {
        "robot_id": "franka_001",
        "driver": "franka",
        "workspace": "~/.PhyAgentOS/fleet/robot_franka"
      }
    ]
  }
}

Field	Type	Description
`embodiments.mode`	string	Set to `"fleet"` to enable multi-robot coordination
`embodiments.shared_workspace`	string	Path to the shared workspace directory for all fleet state files
`embodiments.instances`	array	List of robot instances in the fleet
`instances[].robot_id`	string	Unique identifier for this robot (used in state keys)
`instances[].driver`	string	Driver name matching a built-in or plugin driver
`instances[].workspace`	string	Per-robot workspace directory for ACTION.md and EMBODIED.md

Startup Sequence

Fleet mode requires a specific startup order. Initialize the shared workspace first, then start each Watchdog, and finally the Agent.

Initialize fleet workspace
paos onboard --mode fleet

Creates the shared workspace and scaffolds all required state files.
Start Watchdog for each robot (separate terminals or background processes)
# Terminal 1 — Go2 quadruped python hal/hal_watchdog.py --driver go2_edu --workspace ~/.PhyAgentOS/fleet/robot_go2 # Terminal 2 — Franka arm python hal/hal_watchdog.py --driver franka --workspace ~/.PhyAgentOS/fleet/robot_franka
Start Agent
paos agent --mode fleet

Port conflicts: Each Watchdog uses a different workspace, so state files never collide. If you run multiple Watchdogs on the same machine, ensure each driver's network port (if any) is unique. Use --driver-config to override default ports per instance.

ROBOTS.md Auto-Generation

ROBOTS.md is automatically generated by each Watchdog on startup. It summarizes every robot's identity, driver, capabilities, and connection state.

# ROBOTS.md (auto-generated in shared workspace)
## go2_edu_001
- **driver**: go2_edu
- **type**: quadruped
- **capability**: target_navigation, obstacle_avoidance
- **connection_state**: connected
- **nav_state**: idle

## franka_001
- **driver**: franka
- **type**: arm
- **capability**: pick_up, place, move_to
- **connection_state**: connected
- **nav_state**: idle

The Agent reads ROBOTS.md to understand which robots are available, what they can do, and whether they are currently connected. If a robot disconnects, its Watchdog updates its connection_state to disconnected.

Task Coordination

TASK.md holds the current mission. The Agent decomposes high-level goals into sub-tasks, assigns each to a specific robot, and ORCHESTRATOR.md tracks execution progress.

TASK.md

# Task: Pick apple from table and put in basket

## Sub-tasks
1. [go2_edu_001] navigate to table
2. [go2_edu_001] position near table
3. [franka_001] pick up apple from table
4. [franka_001] move to basket position
5. [franka_001] place apple in basket

ORCHESTRATOR.md

# Orchestrator State
**Progress**: 3/5
**Active Devices**: go2_edu_001, franka_001

## Decision Log
- Step 1: go2_edu_001 → completed
- Step 2: go2_edu_001 → completed
- Step 3: franka_001 → executing
- Step 4: pending
- Step 5: pending

The Agent reads ORCHESTRATOR.md to decide the next action. If a sub-task fails, the Agent replans using LESSONS.md and reassigns or retries.

Shared ENVIRONMENT.md

Multiple Watchdogs write to the same ENVIRONMENT.md using the robots.<robot_id> key namespace. Each robot owns its own section, and the Agent sees a unified view of the entire fleet.

# ENVIRONMENT.md (shared workspace)
## robots
### go2_edu_001
- connection_state: connected
- robot_pose: {x: 1.2, y: 3.4, theta: 0.78}
- nav_state: moving

### franka_001
- connection_state: connected
- robot_pose: {x: 0.0, y: 0.0, theta: 0.0}
- nav_state: idle
- gripper_state: open

## scene
- objects_detected: [apple, table, basket]
- last_updated: 2026-05-21T10:30:00Z

Each Watchdog only writes to its own robots.<robot_id> subsection. The scene section is written by the shared Watchdog (usually the first one or a dedicated perception instance).

Critic Per-Robot Validation

The Critic validates each action against only the target robot's EMBODIED.md — not against all robots. This prevents capabilities of one robot from leaking into validation of another.

Agent selects target robot → EmbodiedActionTool loads target EMBODIED.md → Critic validates action bounds → Writes ACTION.md to that robot's workspace

The Agent explicitly sets robot_id in each action. The EmbodiedActionTool reads only the EMBODIED.md from that robot's workspace. If the action exceeds the robot's capability limits (joint ranges, workspace boundaries, payload), the Critic marks it as rejected with a reason in LESSONS.md.

Key invariant: An action aimed at franka_001 is never validated against go2_edu_001's constraints. Each robot gets exactly the validation it needs.

Debugging Fleet

Fleet debugging is primarily about verifying the right action lands in the right robot's workspace and that shared state is consistent.

Symptom	Check	Command
Robot not responding to actions	ACTION.md in the correct workspace?	`cat ~/.PhyAgentOS/fleet/robot_go2/ACTION.md`
Agent doesn't see a robot	ROBOTS.md has the robot listed?	`cat ~/.PhyAgentOS/fleet/shared/ROBOTS.md`
All actions rejected	Check LESSONS.md for rejection reasons	`cat ~/.PhyAgentOS/fleet/shared/LESSONS.md`
State mismatch between robots	Compare ENVIRONMENT.md sections	`cat ~/.PhyAgentOS/fleet/shared/ENVIRONMENT.md`
Watchdog not consuming actions	Is the correct workspace passed?	Check Watchdog terminal output for `--workspace`

Run each Watchdog in its own visible terminal during debugging. Watching all terminals simultaneously lets you spot which robot is stuck and correlate it with the shared state files.