Documentation

Physiclaw is open-source software that runs AI agents entirely on your own servers. It provides agent orchestration with no cloud dependency, no telemetry, and no vendor lock-in. You deploy on bare metal, virtual machines, or Kubernetes and keep full control of your data and infrastructure.

The project is adapted from OpenClaw (MIT), re-engineered for enterprise bare-metal deployment with zero external dependencies. It is licensed under Apache 2.0.

Most AI agent platforms require cloud connectivity, send telemetry upstream, or lock you into a vendor ecosystem. Physiclaw is different:

• Air-gap ready — Runs fully offline with no external trust boundaries.
• Self-hosted — Deploy on bare metal, VMs, or Kubernetes. Your hardware, your rules.
• Open source — Apache 2.0 licensed, community-driven, transparent by default.
• Zero telemetry — Nothing leaves your network. Ever.

Physiclaw works in three steps:

1. Deploy on your infrastructure — Run Physiclaw on bare metal, VMs, or Kubernetes. Everything stays inside your perimeter.
2. Connect to your tools — Agents plug into Prometheus, Kubernetes, Vault, Slack, and other on-prem services you already use.
3. Chat or command; agents run — From terminal or API you assign tasks. Agents execute on your stack with no data leaving your network.

One-liner

curl -fsSL https://physiclaw.dev | sh -s -- \
  --cluster-name my-agents \
  --enable-gpu \
  --license oss

Docker

docker run -d \
  --name physiclaw-core \
  --gpus all \
  -p 8090:8090 \
  -v /var/physiclaw/data:/data \
  -e PL_LICENSE=oss \
  -e PL_CLUSTER_NAME=my-agents \
  ghcr.io/physiclaw/core:latest

Helm (Kubernetes)

helm repo add physiclaw https://physiclaw.dev
helm repo update

helm install physiclaw-core physiclaw/core \
  --namespace physiclaw \
  --create-namespace \
  --set global.license=oss \
  --set gpu.enabled=true \
  --set persistence.size=100Gi

Build from source

git clone https://github.com/CommanderZed/Physiclaw.git
cd Physiclaw
make deps
make build
./bin/physiclaw-server \
  --config config/default.yaml \
  --data-dir /var/physiclaw/data

Physiclaw ships with pre-built agent personas designed for enterprise workloads. Each persona loads a dedicated toolchain and operates within defined boundaries so you can grant autonomy where it matters while keeping control.

• The SRE — Site Reliability Engineering. Uses Prometheus, Kubernetes, Terraform, Grafana, and alerting. Monitors uptime and SLOs, manages infrastructure as code, and can auto-remediate common failures (restart pods, scale, run playbooks) within policy. Suited for teams that want agents to handle tier-1 response and escalation.
• The SecOps Guardian — Security Operations. Toolchain includes log analysis, CVE scanning, IAM, SIEM, and compliance checks. Triages alerts, suggests or applies policy-driven hardening, and supports audit readiness. Actions can be configured to require approval for sensitive changes (e.g. firewall, IAM) while allowing read-only and low-risk automation.
• The Data Architect — Data Engineering. Works with SQL, ETL pipelines, Snowflake, dbt, and data quality frameworks. Optimizes schemas, orchestrates pipelines, and runs quality checks. Designed for data teams that want agents to own routine pipeline ops and reporting while keeping destructive or PII-touching actions under governance.
• The Code Janitor — Code Quality. Covers refactoring, unit tests, linting, CI/CD, and docs. Keeps CI green and tech debt in check. Can be scoped to specific repos and branches; merge and release actions can be gated by approval or role so autonomy is limited to safe operations.

Agents execute tasks by reasoning over your request, selecting tools from their persona toolchain, and operating in an isolated workspace. You control how much autonomy they have and how actions are approved and audited.

Execution model

Each agent run gets a sandboxed workspace (filesystem and network scoped by config). The agent chooses which tools to call (e.g. query Prometheus, run a Terraform plan, execute a SQL query) and in what order. Tool outputs are fed back into the model for the next step until the task is done or a limit is reached. All tool invocations are logged and can be tied to an audit trail.

Autonomy levels

You can configure agents to run in fully autonomous mode (execute and report), approval-required mode (propose actions and wait for human approval), or read-only mode (query and suggest only). This is typically set per persona or per environment (e.g. production requires approval, staging allows autonomy). Escalation paths (e.g. notify Slack, create a ticket) are configurable when an agent needs human input or when a run fails.

Guardrails

Tool use can be restricted by allowlists (e.g. which APIs or commands an agent may call), rate limits, and scope (e.g. which namespaces or projects). Sensitive operations (key access, destructive changes) can be gated behind approval or restricted entirely. This gives enterprise teams confidence to grant autonomy for routine work while keeping high-impact actions under control.

Every layer runs inside your perimeter. Physiclaw implements defense-in-depth with five concentric security rings so you can meet strict compliance and air-gap requirements without trading off on agent capability.

Attestation and audit

Agent runs and tool calls can be recorded in a tamper-evident Merkle log or similar backend. Outputs can be signed (e.g. with Cosign) so you have cryptographic proof of what an agent did and when. This supports compliance (SOC 2, HIPAA, FedRAMP) and internal governance. Audit logs can be exported to your SIEM or retention store (WORM) so nothing is lost and everything is attributable.

Secrets and keys

API keys, model weights, and RAG credentials are never stored in plaintext on disk. Support for HSM, TPM 2.0, and Vault lets you seal secrets to hardware identity and rotate them without agent downtime. Key material is available only to the process that needs it and is not exposed in logs or telemetry.

Physiclaw is built for organizations that need agent autonomy without losing control. Deployment patterns, governance, and operational guardrails are designed so security and platform teams can standardize how agents run across environments.

Deployment patterns

Run a single node for dev or small teams; scale horizontally with multiple gateway and worker nodes for production. You can deploy behind your existing load balancer and identity provider. Agents can be scoped by namespace, project, or tag so different teams or environments get the right personas and tool access without cross-tenant leakage.

Governance

Define who can invoke which agents and with what autonomy level (e.g. read-only vs. autonomous). Approval workflows can require one or more human approvals for sensitive actions. All invocations and decisions are auditable. This lets you roll out autonomy gradually: start with read-only and recommendations, then enable approved actions, then autonomous execution where policy allows.

Operational control

You own the full stack: models, inference runtime, vector store, and audit backend. There is no vendor lock-in or mandatory SaaS. You can air-gap the entire system, run in disconnected regions, and meet regulatory requirements (e.g. data residency, no telemetry) while still giving teams the benefits of AI-powered automation.

Everything is a config change. Swap runtimes, vector stores, and audit backends in YAML. No vendor calls, no lock-in.

# physiclaw.yaml
runtime:
  backend: "vllm"           # vllm, tgi, ollama, triton
  model: "llama-3-70b"     # any GGUF / safetensors weight
  gpu_layers: "auto"       # offload control
  max_concurrent: "64"     # per-node parallelism

knowledge:
  store: "pgvector"        # pgvector, faiss, milvus, qdrant
  embedder: "bge-large"   # on-prem embedding model
  chunker: "semantic"
  reranker: "cross-encoder"

audit:
  backend: "merkle-log"    # tamper-evident storage
  signing: "cosign"       # cryptographic verification
  export: "siem-sink"     # compliance export
  retention: "forever"     # WORM retention

Supported runtimes: vLLM, TGI, Ollama, GGUF, ONNX, Triton

Supported vector stores: pgvector, FAISS, Milvus, Qdrant

Supported embedding models: BGE-Large, E5-Mistral, Nomic-Embed, Local ONNX

Physiclaw connects to common enterprise on-prem services so agents can use the tools you already run inside your perimeter. Supported integrations include:

• Prometheus (metrics and alerting)
• Grafana (dashboards)
• Kubernetes (orchestration)
• Vault (secrets and identity)
• LDAP / Active Directory (identity)
• PostgreSQL (data and vector store)
• GitLab, Jenkins (source and CI)
• SIEM, Slack, Microsoft Teams
• OpenTelemetry, Splunk, Elastic

From the Physiclaw core repo:

pnpm install
pnpm dev        # development mode
pnpm build      # build
node physiclaw.mjs gateway   # start gateway

The marketing site and docs live in the website/ directory (Next.js). To run locally:

cd website
npm install
npm run dev

Open http://localhost:3000. The live site is at https://www.physiclaw.dev.

/
├── src/                # Core engine
│   ├── agents/         # Agent execution, tools, workspace
│   ├── cli/            # CLI (Commander.js)
│   ├── config/        # YAML config, Zod validation
│   ├── daemon/         # Service management (launchd/systemd)
│   ├── gateway/        # HTTP/WebSocket control plane
│   ├── plugins/        # Plugin infrastructure
│   ├── providers/      # AI model provider integrations
│   └── security/       # Audit, scanning, hardening
├── skills/             # Agent personas (sre, secops, data-architect, code-janitor)
├── config/             # Default YAML
├── packages/           # Shared packages
├── extensions/         # Extension plugins
├── website/            # Marketing + docs (Next.js)
├── Dockerfile
├── docker-compose.yml
└── physiclaw.mjs       # CLI entry