# PUDA

> Explore guides and tutorials to start building on PUDA's platform
- [Getting Started](/docs/getting-started.md): PUDA is a hardware harness for Physical AI. Read more about it at puda.co/blog/whitepaper.

## Overview

- [Architecture](/docs/overview/architecture.md): Physical machines speak countless protocols, expose incompatible APIs, and resist the kind of uniform control that software expects. AI agents and autonomous systems need a single, reliable way to observe and act on hardware—without bespoke integrations for every device.
- [PUDA CLI](/docs/overview/puda-cli.md): LLMs are exceptionally good with text-based interfaces. CLIs and Markdown are a natural fit because:
- [Communication](/docs/overview/communication.md): The foundation of PUDA is a high-performance messaging backbone powered by NATS. In this layer, every entity—whether a hardware machine, a CLI tool, or a logger—operates as a first-class participant within a unique subject namespace.
- [Under the Hood](/docs/overview/under-the-hood.md): Translating natural language to machine execution

## Setup

- [Opentrons OT-2 All-in-One Setup](/docs/setup/opentrons-ot2-all-in-one.md): This guide sets up a single machine to run the full PUDA stack for an Opentrons OT-2:
- [Hardware Requirements](/docs/setup/hardware-requirements.md): PUDA deployments usually have two kinds of machines: an AI agent host and one or more edge devices. The AI agent host runs the coding agent and connects to PUDA services. Edge devices run machine-specific adapters near the hardware.
- [Network](/docs/setup/network.md): PUDA runs as a distributed architecture. Every participant in the system must be able to reach the central NATS server so commands, telemetry, events, and logs can move through the same communication layer.
- [NATS Server](/docs/setup/nats-server.md): The NATS server is the central communication point for PUDA. It should run on a machine that stays powered on, because the PUDA CLI, edge services, and logger services all depend on it for commands, telemetry, events, and logs.
- [Integrating a New Machine](/docs/setup/integrating-a-new-machine.md): Each machine in PUDA runs an edge service. The edge service wraps the machine's hardware API, connects to NATS, and exposes machine commands to the rest of the PUDA system.
- [Hermes Agent](/docs/setup/hermes-agent.md): Skip this step if you already have an AI agent installed on your machine that can access the filesystem and shell. We recommend Hermes Agent because it has a well-built learning loop and gets better at learning your workflows the more you use it.
- [PUDA CLI and Skills](/docs/setup/puda-cli-and-skills.md): Install the PUDA CLI and PUDA skills in the shell environment used by your AI agent. This lets Cursor, Claude, Hermes, or any shell-capable agent discover machines, run PUDA commands, and follow PUDA workflows.
- [Machine Skills](/docs/setup/machine-skills.md): After your AI agent can see PUDA machines, teach it how to use each machine. Do this in natural language first: give the agent specific operating instructions, ask it to test them against the available PUDA commands, and turn the resulting patterns into machine skills.
- [Livestream](/docs/setup/livestream.md): If you want the AI agent to have vision capabilities in addition to simply executing and looking at telemetry, run a livestream server on the PUDA machine host. This setup supports USB cameras, webcams, and IP cameras, with live video available over RTSP, RTMP, HLS, or WebRTC.

## Using PUDA

- [Workflow Skills](/docs/using-puda/workflow-skills.md): A workflow skill is reusable operational memory for a multi-step task. It describes the exact sequence of PUDA commands, verification steps, and failure handling an agent should follow to complete a task reliably.
- [Cron Jobs](/docs/using-puda/cronjobs.md): Use cron jobs when a PUDA task should run on a schedule, such as every morning before the lab opens, once per hour during a long experiment, or every night after instruments are idle.

## Observability

- [PUDA Logger](/docs/observability/logging-service.md): By default, the PUDA CLI uses SQLite for local storage. This is enough for a local workstation, quick experiments, and single-user development.
- [Hermes Logger](/docs/observability/hermes-logger.md): Hermes Logger is a Hermes observer plugin that writes structured agent telemetry to InfluxDB. It captures user prompts, LLM API calls (including reasoning payloads), tool calls, subagent delegation, and approval flows for every Hermes session on a machine.
- [Grafana Dashboard](/docs/observability/grafana-dashboard.md): Once the PUDA Logger is writing to InfluxDB, you can add Grafana for dashboards, exploration, and alerts. Grafana queries the same machinestatus and machinecommands measurements the logger writes from NATS.

## Troubleshoot

- [Connection Troubleshoot](/docs/troubleshoot/connection-troubleshoot.md): Restart an edge service when it stops responding, after you change configuration, or after you deploy new driver code.
- [Docker API Troubleshoot](/docs/troubleshoot/docker-api-troubleshoot.md): Use this page to fix common Docker API access issues during PUDA setup.
- [Observability Troubleshoot](/docs/troubleshoot/observability-troubleshoot.md): Use this page when Hermes can run PUDA commands, but command results or Hermes events are not appearing in InfluxDB, logger output, or the Grafana event timeline.

## Other Pages

- /
- /blog
- /blog/archive
- /blog/authors
- /blog/authors/hongzhao
- /blog/first-blog-post
- /blog/tags
- /blog/tags/puda
- /docs/category/observability
- /docs/category/overview
- /docs/category/setup
- /docs/category/troubleshoot
- /docs/category/using-puda
- /markdown-page