PhyAgentOS — CLI Reference

`paos onboard`

Initialize a new PhyAgentOS workspace. Creates the configuration file and workspace directory with all protocol Markdown files.

paos onboard

Flag	Type	Description
`--workspace PATH`	string	Custom workspace path. Default: `~/.PhyAgentOS/workspace`
`--force`	flag	Overwrite existing workspace files without confirmation prompt

Generated files:

~/.PhyAgentOS/config.json — system configuration
ENVIRONMENT.md — environment state source of truth
EMBODIED.md — robot capability profile
ACTION.md — action dispatch queue
LESSONS.md — failure experience log

Tip: Run paos onboard again after upgrading PhyAgentOS to refresh configuration templates to the latest version.

`paos agent`

Start the interactive agent (Track A). The Planner-Critic loop runs here, reading environment state and dispatching actions to Track B.

paos agent

Flag	Type	Description
`-m "message"`	string	Single-turn mode: send one instruction and exit. Without this flag, agent starts in interactive REPL mode.
`--model NAME`	string	Override the LLM model. Example: `--model openrouter/anthropic/claude-sonnet-4`
`--workspace PATH`	string	Custom workspace path. Default comes from `config.json`

Interactive Mode

The default. Agent presents a prompt (>) and waits for natural-language tasks. Sessions persist until Ctrl+C or /exit.

Single-Turn Mode

Use -m for scripting and automation. The agent processes one instruction and exits — ideal for CI pipelines and batch testing.

paos agent -m "Move to the kitchen and describe what you see." --model openrouter/openai/gpt-4o-mini

`paos gateway`

Start the long-running gateway service. Provides channel integration (Telegram, Slack, Feishu) and heartbeat-based scheduling for the agent loop.

paos gateway

Flag	Type	Description
`--port PORT`	int	HTTP server port. Default: 8080
`--host HOST`	string	HTTP server host. Default: 0.0.0.0

The gateway integrates external messaging channels and can trigger the agent on incoming messages. Configure channels in ~/.PhyAgentOS/config.json under the channels key.

Use case: Deploy the gateway on a cloud server to control your robot via Telegram or Slack from anywhere.

`python hal/hal_watchdog.py`

Start the hardware watchdog (Track B). Polls ACTION.md for pending actions and dispatches them to the specified driver.

python hal/hal_watchdog.py --driver simulation

Flag	Type	Description
`--driver NAME`	string	Required. Select the driver. Built-in: `simulation`, `rekep_sim`. External: `rekep_real`, `go2_edu`
`--gui`	flag	Enable the GUI window that visualizes the simulation scene in real-time
`--interval SECONDS`	float	Polling interval for checking `ACTION.md`. Default: 1.0
`--driver-config PATH`	string	Path to a driver-specific YAML/JSON config file. Example: `--driver-config configs/drivers/go2_edu.yaml`
`--workspace PATH`	string	Override the workspace directory. Default from `config.json`
`--robot-id ID`	string	Specify which robot to control. Required in Fleet mode. Example: `--robot-id go2_edu_001`

# Simulation with GUI and faster polling
python hal/hal_watchdog.py --driver simulation --gui --interval 0.5

# Real robot with custom config
python hal/hal_watchdog.py --driver rekep_real --driver-config configs/drivers/franka.yaml --robot-id franka_001

`python scripts/run_runtime_watchdog.py`

Start the runtime watchdog (V2 session-based executor). Reads SESSIONS.md and dispatches sessions to the appropriate SkillRuntime and TargetAdapter.

python scripts/run_runtime_watchdog.py --workspace /tmp/paos_runtime

Flag	Type	Description
`--workspace PATH`	string	Path to the runtime workspace. Required.
`--once`	flag	Run a single pass through all pending sessions and exit. Without this flag, the watchdog runs indefinitely in a polling loop.
`--environment-workspace PATH`	string	Separate workspace for environment state. Used in Fleet mode when the environment is maintained in a shared workspace distinct from per-robot session workspaces.

Fleet mode: Use --environment-workspace to point to the shared workspace that holds the global ENVIRONMENT.md. Each robot's watchdog reads from the shared environment but writes sessions to its own workspace.

`python scripts/init_runtime_workspace.py`

Initialize a runtime workspace with all required configuration files and directory structure for session-based execution.

python scripts/init_runtime_workspace.py --workspace /tmp/paos_runtime

Flag	Type	Description
`--workspace PATH`	string	Path where the runtime workspace will be created. Required.

Generated structure:

TARGETS.md — runtime target registry
SKILLS.md — runtime skill registry
SESSIONS.md — session queue
configs/runtime/ — sensor and perception YAML configs

`python scripts/deploy_rekep_real_plugin.py`

Deploy the ReKep real-robot plugin for natural-language grasping with robot arms (Dobot, Franka, etc.).

python scripts/deploy_rekep_real_plugin.py --repo-url https://github.com/baiyu858/PhyAgentOS-rekep-real-plugin.git

Flag	Type	Description
`--repo-url URL`	string	URL of the ReKep plugin repository. Required unless the default is set.
`--with-solver`	flag	Also install the ReKep constraint solver for advanced grasping pose optimization
`--no-install-deps`	flag	Skip Python dependency installation (use if you're managing deps manually)
`--ref BRANCH`	string	Git branch or tag to checkout. Default: `main`

After deployment: Start the watchdog with python hal/hal_watchdog.py --driver rekep_real to use the plugin.

Quick Reference Table

Four common startup scenarios and the exact commands for each terminal.

Scenario	Terminal 1 (Track B / Watchdog)	Terminal 2 (Track A / Agent)
Single-machine simulation	`cd PhyAgentOS python hal/hal_watchdog.py --driver simulation --gui`	`cd PhyAgentOS paos agent`
Single-machine real robot	`cd PhyAgentOS python hal/hal_watchdog.py --driver rekep_real --driver-config configs/drivers/franka.yaml`	`cd PhyAgentOS paos agent --model openrouter/anthropic/claude-sonnet-4`
Fleet mode	`# Robot A python hal/hal_watchdog.py --driver go2_edu --robot-id go2_edu_001 --workspace /tmp/paos_fleet/robot_a # Robot B python hal/hal_watchdog.py --driver franka --robot-id franka_001 --workspace /tmp/paos_fleet/robot_b`	`cd PhyAgentOS paos agent --workspace /tmp/paos_fleet/shared`
Runtime session test	`python scripts/init_runtime_workspace.py --workspace /tmp/paos_runtime_smoke python scripts/run_runtime_watchdog.py --workspace /tmp/paos_runtime_smoke --once` Single terminal: init workspace then run a single pass. Session `sess_dummy_smoke` runs and reports success.