Skip to content
PUDAPPublic

About

Hardware Harness for Physical AI

Resources

Security policy

Stars

11 stars

Watchers

0 watching

Forks

Latest commit

 

History

400 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

PUDA

PUDA

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.

Release PyPI Docs License: MIT Stars

Quick start · How it works · Agent skills · Under the hood · Repository layout · Development · Docs

Built by PUDAP · puda.co · Paper · MIT

Connect
Each machine runs a PUDA edge that wraps its driver and speaks NATS. puda machine list finds every edge on the network.

Plan
Your agent writes a protocol: JSON steps of atomic machine commands. puda protocol validate checks it before anything moves.

Run
puda protocol run executes step by step, in parallel where allowed, and stops on the first error. Risky steps wait for a yes.

Verify
Runs, samples and measurements are stored per project. puda project hash returns a deterministic SHA-256 of the dataset.

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).

Quick start

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 version

Give 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 profile

Or 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.

How it works

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
Loading
  1. Edges wrap each machine's driver and expose atomic commands plus telemetry over NATS.
  2. The CLI is the single interface for agents: discover machines, run protocols, query data, check health. Most commands emit JSON (--human for text).
  3. Loggers persist every command response and telemetry stream, so any run or time window can be retrieved later.
  4. Environments isolate each lab's machines, drivers, data and credentials, so the same skills always load the right context.

Agent skills

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.

Under the hood

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:

  1. Modularity — driver, communication and orchestration layers are separate, so each can scale, change or be replaced independently.
  2. AI-native — every capability is a stable, programmatic interface with atomic machine commands; agents are first-class operators, not an afterthought.
  3. Scalability — from a single machine to a fleet of edges.

Repository layout

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.

Development

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)

License

MIT © PUDAP

About

Hardware Harness for Physical AI

Resources

Security policy

Stars

11 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages