The runtime environment for Physical AI.
Let AI agents plan, run and record work on real machines — lab instruments, robot arms, pumps, sensors — with every run hashed for verifiable provenance.
Quick start · How it works · Agent skills · Under the hood · Repository layout · Development · Docs
|
Connect |
Plan |
Run |
Verify |
Headless by design, built for agents. PUDA is a hardware-agnostic, LLM-agnostic platform with no bundled UI. You drive it with an AI agent — Cursor, Claude Code, Hermes Agent, OpenClaw or your own — using the agent skills that ship in this repository: ready-made playbooks for setting up projects, writing protocols, running experiments and generating reports. When a human-facing view helps, ask your agent to build a dashboard (for example in Streamlit).
Install the CLI from the latest release (Linux x86_64 shown; macOS, Windows and ARM builds are attached too):
curl -fsSL https://github.com/PUDAP/puda/releases/latest/download/puda_linux_x86_64.tar.gz \
| tar -xz puda
sudo install puda /usr/local/bin/ && puda versionGive your agent the PUDA skills, then start a project:
puda skills install # release-pinned official skills
puda login -u <username> # name recorded with your runs
puda init ./my-project --name "My Project"
puda machine list # discover edges on your NATS profileOr skip the typing and paste this into your agent:
Install the latest PUDA CLI from https://github.com/PUDAP/puda/releases, add it to my PATH,
then install the PUDA skills with `puda skills install`.
Full setup — NATS server, edges, clock sync, security — is at docs.puda.co.
flowchart LR
A["AI agent + PUDA skills"] -- "puda CLI" --> N(("NATS"))
N <--> E1["Edge: robot arm"]
N <--> E2["Edge: pump"]
N <--> E3["Edge: instrument"]
N -- "responses and telemetry" --> L[("Logger database")]
A -- "query and hash runs" --> L
- Edges wrap each machine's driver and expose atomic commands plus telemetry over NATS.
- The CLI is the single interface for agents: discover machines, run protocols, query data, check health. Most commands emit JSON (
--humanfor text). - Loggers persist every command response and telemetry stream, so any run or time window can be retrieved later.
- Environments isolate each lab's machines, drivers, data and credentials, so the same skills always load the right context.
Skills live in skills/ and are versioned with the CLI. puda skills install installs the set matching your CLI release.
| Skill | What your agent learns |
|---|---|
puda |
Set up the CLI, projects and profiles; inspect machines |
puda-protocol |
Create, validate and run protocol JSON |
puda-data |
Extract, analyse, hash and report on run data |
puda-database |
Ad-hoc SQL and schema inspection on a project database |
puda-deployment |
Install, commission and troubleshoot edge deployments |
puda-edge |
Build and update Python edge drivers for a new machine |
puda-manual-ui |
Build manual-control operator UIs |
Migrating from the old PUDAP/skills submodule? See the skills migration guide.
| NATS | All message routing between components: one uniform, loosely coupled communication layer for every machine and service. |
| Layered drivers and orchestration | The control path separates how a device works from how experiments are composed and executed. |
| CLI | Versioned commands expose every capability, so agents use a stable interface instead of brittle one-off scripts. |
| Environments | Each environment's machines, drivers, data and credentials are isolated from every other. |
| Verification | Run data is extracted, SHA-256 hashed and stored, giving every run provenance from command to result. |
Design goals:
- Modularity — driver, communication and orchestration layers are separate, so each can scale, change or be replaced independently.
- AI-native — every capability is a stable, programmatic interface with atomic machine commands; agents are first-class operators, not an afterthought.
- Scalability — from a single machine to a fleet of edges.
puda/
├── apps/
│ ├── cli/ # Go CLI agents use to talk to PUDA
│ ├── docs/ # docs.puda.co source (Docusaurus, standalone pnpm project)
│ └── loadgen/ # Go load generator for NATS and fleet-scale tests
├── libs/
│ ├── python-sdk/ # Python SDK, published as `puda` on PyPI
│ └── db/ # PostgreSQL client (puda-db)
├── infra/
│ ├── nats/ # NATS server topologies and JetStream resources
│ └── chrony/ # Site NTP server; edge hosts sync to it
├── skills/ # Release-aligned agent skills
├── test-edge/ # Software-only edge for local testing
├── pyproject.toml # uv workspace (Python)
└── package.json # Nx workspace, installed with pnpm
Python packages share one uv workspace (pyproject.toml) whose members are libs/*, services/* and test-edge; there is no services/ directory yet. Workspace packages reference each other locally:
[tool.uv.sources]
puda = { workspace = true }The Go apps keep their own modules and are not part of uv.lock. A small root Go module embeds the compatibility.json policy the CLI uses to check edge SDK versions; see CLI / Python SDK compatibility.
Prerequisites: Python ≥ 3.12 and uv · Go 1.26+ for apps/cli and apps/loadgen · Docker for the stacks under infra/ · Node.js and pnpm for Nx.
uv sync # every Python workspace member in one venv
cd apps/cli && just build # build the CLI
cd apps/docs && pnpm install && pnpm start # docs site at localhost:3000 (Node ≥ 20)- CLI commands and contracts:
apps/cli/README.md· contributing:apps/cli/CONTRIBUTING.md - Docs site:
apps/docs/README.md— edit pages underapps/docs/docs/ - Test without hardware:
test-edge/README.md - NATS layouts:
infra/nats/README.md - Security reports:
SECURITY.md
MIT © PUDAP