claws platform

Agent-native cloud infrastructure — built on open-source Coolify, extended so AI agents can ship full stacks without a human in the loop.

Website · Console · Docs · MCP · Local MCP (dev) · Deploy runbook (ops)

---

What this is

This directory is the Laravel 12 application behind claws.software: a maintained fork of Coolify (Apache-2.0) that turns a proven self-hostable PaaS into cloud for AI agents.

Coolify gives us the hard parts already solved — Docker deployments, databases, reverse proxy, queues, operator UI patterns. claws adds what human-first PaaS products were never designed for:

• Agents as first-class principals (not sub-users with pasted API keys)
• Cryptographic auth (HTTP Signatures + UCAN capabilities)
• MCP and CLI surfaces so Claude, OpenClaw, Hermes, and similar runtimes can provision infrastructure from conversation
• Wallet-native metering and receipts so autonomous workloads can pay, pause, and prove spend

An agent can register, connect via MCP or CLI, and create a backend, a frontend, a database, and object storage in one flow — push code from gitlawb, deploy containers, and receive a public URL — without waiting for a human to click Approve.

Humans still matter as operators: they claim agents, fund escrow, set capability ceilings, and audit receipts. They are not the gate on every deploy.

---

Vision

We are building decentralized cloud primitives with a centralized control plane today.

Layer	Today (v1)	Direction
Control plane	Laravel app on managed VPS (console.claws.software)	Stays the orchestration + policy layer
Compute	Dedicated Hetzner pool — agent workloads isolated from the console	Akash — permissionless, market-priced compute
Storage	S3-compatible / local volumes via Coolify	Walrus — decentralized blob storage
Version control	gitlawb — decentralized Git, push-to-deploy	Same identity (did:gitlawb) for Git access and claws auth
Identity & auth	did:gitlawb agents, Web3Auth operators, UCAN capabilities	Wallet-native, attenuatable, auditable
Settlement	Trial credits + per-deploy/per-hour metering (USDC roadmap)	On-chain receipts operators can reconcile

Be honest about the arc: production today routes agent containers to a centralized compute pool so we can ship a reliable MVP. The architecture is deliberately provider-shaped — compute, storage, Git, and billing are separate adapters — so we can migrate execution to Akash, persistence to Walrus, and keep the same agent API.

The goal is not “another dashboard with an AI chatbot bolted on.” The goal is infrastructure where software that runs itself can also provision itself.

---

Why we fork Coolify

Coolify is mature open-source PaaS software: servers, applications, databases, deployments, webhooks, and an Actions layer we can extend instead of reinventing.

Our fork policy (see .claws/UPSTREAM.md):

1. Track upstream on coollabsio/coolify branch v4.x and merge regularly.
2. Extend additively — new code lives under App\Claws\, new tables prefixed claws_, new middleware and MCP tools.
3. Keep business logic in Actions — REST, Livewire, MCP, and webhooks are thin adapters over app/Actions/.
4. Stay clearly branded — this is claws, not Coolify Labs. We attribute upstream; we do not impersonate it.

Trademark: “Coolify” belongs to the upstream project. claws.software is a separate product that modifies and extends that codebase for agent workloads. See NOTICE.

---

How an agent uses claws

  ┌─────────────┐     MCP / CLI / signed HTTP      ┌──────────────────────┐
  │  AI Agent   │ ───────────────────────────────► │  claws control plane │
  │ did:gitlawb │ ◄─────────────────────────────── │  (this Laravel app)  │
  └─────────────┘     receipts, URLs, balances     └──────────┬───────────┘
                                                              │
                    ┌─────────────────────────────────────────┼─────────────────────────┐
                    ▼                     ▼                   ▼                         ▼
              Compute pool          Postgres / Redis      gitlawb repos            Operator console
           (Docker / Traefik)      (managed services)   (push-to-deploy)         (claim, fund, audit)

Typical flow

1. Register — agent gets a did:gitlawb identity and an isolated workspace (team).
2. Connect — MCP (POST /api/v1/claws/mcp) or CLI (claws onboard) with HTTP Signatures on every call.
3. Authorize — UCAN tokens gate what the agent may do (coolify:deploy, coolify:database.create, …).
4. Ship — create applications, databases, and storage; deploy from gitlawb or container images.
5. Meter — usage debits agent balance; low balance triggers suspend. Operators top up escrow.

Full API and MCP tool lists live at docs.claws.software. For a local smoke test against this repo, start with .claws/MCP-LOCAL.md.

---

What agents can provision

Through MCP tools and the Coolify Actions layer, an agent can orchestrate a full product surface in one session:

Primitive	What the agent gets
Compute	Containerized backend or frontend, routed through Traefik, on an isolated pool server
Database	Real Postgres (and other Coolify-supported data stores) scoped to the agent's team
Storage	Object storage and volumes for assets, uploads, and build artifacts
Serverless	Short-lived execution with metered billing (roadmap hardening)
Version control	Deploy from gitlawb — same DID for Git identity and claws identity
Payments	Wallet-bound spend via metering + escrow (USDC settlement on roadmap)

The agent describes intent; claws translates it into signed infrastructure operations with auditable receipts — not opaque console clicks.

---

Code layout

coolify/
├── app/
│   ├── Actions/          ← Coolify business logic (upstream + shared)
│   └── Claws/            ← Agent identity, UCAN, MCP, billing, gitlawb
├── config/claws.php      ← Feature flags, pool routing, trial promo, …
├── routes/api.php        ← /api/v1/claws/* agent surface
├── tests/Claws/          ← Fast test slice (sqlite :memory:)
└── .claws/               ← Deploy runbooks, upstream merge notes, MCP local setup

Integration branch: claws/main in clawssoftware/claws-v1.
Product marketing site: clawssoftware/claws-ui (separate repo).

---

Development

Requirements: PHP 8.4+ (sodium, pdo_sqlite, redis, intl, bcmath, pcntl, sockets) or Docker.

From this directory:

composer install
cp .env.example .env
php artisan key:generate

# Claws test slice — no Postgres required
php artisan test --compact tests/Claws tests/Feature/Claws

Style gate (matches CI):

vendor/bin/pint --test app/Claws config/claws.php config/claws_route_capabilities.php tests/Claws tests/Feature/Claws

For a full stack (Postgres, Redis, Soketi, Horizon), use the compose files here and docs.claws.software, then layer claws env vars from .env.example.

---

Documentation

Public docs: docs.claws.software — onboarding, MCP/CLI guides, operator flows, and API reference.

In this repo (contributors and self-hosters):

Topic	Where
Getting started & architecture	docs.claws.software
Agent onboarding & MCP tools	docs.claws.software/mcp
Installation (full stack)	docs.claws.software/installation
Merge upstream Coolify	.claws/UPSTREAM.md
Production deploy (v1, ops)	.claws/DEPLOY.md
Claude Desktop / Cursor MCP (local dev)	.claws/MCP-LOCAL.md
Security & responsible disclosure	SECURITY.md
Upstream Coolify docs	coolify.io/docs

---

Contributing

1. Open an issue or pick an existing one on GitHub.
2. Branch from claws/main as claws/<feature>/<slug>.
3. Run the Claws test slice before opening a PR.
4. Bugfixes that benefit all Coolify users → consider upstream to coollabsio/coolify. Agent-first features → land under App\Claws\ here.

---

License

This directory is a derivative work of Coolify, licensed under Apache License 2.0. See LICENSE and NOTICE for attribution requirements.

---

_{Open-source foundation · agent-native execution · decentralized by design}