1. Prerequisites
| Requirement | Version | Check |
|---|---|---|
| Python | ≥ 3.11 | python --version |
| Git | any recent | git --version |
| LLM API key | OpenAI / Azure / compatible | Sign up at your provider |
2. Install
Clone the repository and install PhyAgentOS in editable mode.
git clone https://github.com/SYSU-HCP-EAI/PhyAgentOS.git
cd PhyAgentOS
python -m venv .venv
source .venv/bin/activate
pip install -e .Expected output: Successfully installed PhyAgentOS-0.0.5 and the paos CLI becomes available.
Alternative: Conda
conda env create -f environment.yml
conda activate paos
pip install -e .Optional: Development Dependencies
pip install -e ".[dev]"pip install -e . fails, make sure you're using Python ≥ 3.11. Run python --version to confirm.
3. Initialize the Workspace
paos onboard creates the configuration file and workspace directory with all protocol Markdown files.
paos onboardThis does three things:
- Creates
~/.PhyAgentOS/config.json— your system configuration - Creates
~/.PhyAgentOS/workspace/— the single-machine workspace - Generates protocol files:
ENVIRONMENT.md,EMBODIED.md,ACTION.md,LESSONS.md
paos onboard again after upgrading PhyAgentOS to refresh configuration templates.
4. Start the System — Your First Closed Loop
Open two terminals. One runs the hardware watchdog (Track B), the other runs the Agent (Track A).
Terminal 1: Start the Simulation Watchdog
cd PhyAgentOS
python hal/hal_watchdog.py --driver simulationExpected output:
[Watchdog] Driver 'simulation' loaded
[Watchdog] Profile installed → EMBODIED.md
[Watchdog] Polling ACTION.md…Terminal 2: Start the Agent
cd PhyAgentOS
paos agentOnce the agent prompt appears, type a task:
> Look at what is on the table, then grasp that apple for me.You should see action execution logs in Terminal 1 and a completion confirmation from the Agent in Terminal 2.
What Just Happened
Agent → planned action → Critic validated → wrote ACTION.md → Watchdog read it → Driver executed → state wrote back to ENVIRONMENT.md.
Verify the Result
Open ~/.PhyAgentOS/workspace/ENVIRONMENT.md — you'll see the updated scene graph with the apple's new position.
5. Optional: Runtime Session Smoke Test
PhyAgentOS also has a session-based runtime (SESSIONS.md → WatchdogSupervisor → policy client → target). Run this lightweight test to verify it works.
python scripts/init_runtime_workspace.py --workspace /tmp/paos_runtime_smoke
python scripts/run_runtime_watchdog.py --workspace /tmp/paos_runtime_smoke --onceExpected: the session sess_dummy_smoke is marked succeeded, and an episode summary is written to /tmp/paos_runtime_smoke/artifacts/runtime/<session_id>/episode.json.
6. Optional: Install the ReKep Real-Robot Plugin
If you have a real robot arm (Dobot, Franka, etc.), install the ReKep plugin for natural-language grasping.
python scripts/deploy_rekep_real_plugin.py \
--repo-url https://github.com/baiyu858/PhyAgentOS-rekep-real-plugin.gitAfter installation, start the watchdog with the real driver:
python hal/hal_watchdog.py --driver rekep_real