ClawQL: A Practical, Hybrid Decentralized GitHub Alternative

The Problem

Modern software development depends on artifacts that get published once and then trusted indefinitely: a tagged release, a Docker image, a Helm chart, an npm package. The platforms hosting these artifacts — GitHub, GitLab, npm, Docker Hub — are excellent for collaboration but were never designed to guarantee that what you download today is the same thing that was published originally.

This matters more than it used to, for a few reasons:

• Tags can be moved. A v2.1.0 release today might not be the same bytes as v2.1.0 six months ago, whether through human error, a compromised account, or a deliberate supply chain attack.
• Most consumers — humans, CI pipelines, Kubernetes clusters, and increasingly AI agents — have no way to verify exactly what they're running or where it came from.
• Build environments are typically mutable. Reproducing an exact build from six months ago, byte for byte, is hard even when you have the source code.
• AI agents that autonomously pull dependencies, deploy services, or apply updates need machine-readable information about what's safe to run and what to do if something goes wrong — information that doesn't exist in a typical repository today.

ClawQL addresses this without asking anyone to abandon GitHub, Git, or their existing workflows. The core idea: day-to-day collaboration stays exactly as it is. Official releases become permanent, verifiable, and self-describing.

The Hybrid Architecture

ClawQL has four layers, each handling a distinct part of the problem.

Layer 1: Collaboration — Radicle, with GitHub as a Mirror

Day-to-day development — branches, pull requests, code review, issues — happens on Radicle, a peer-to-peer Git-compatible collaboration network. Radicle gives every contributor a cryptographic identity, replicates repositories directly between peers without a central server, and supports private repositories through access lists.

GitHub remains in the picture as a read-only mirror. Anyone can still find your project on GitHub, star it, browse it, and clone it — but the mirror displays a banner pointing to the canonical source on Arweave (Layer 3) for anything that matters for verification. Nothing changes about how your project looks to the outside world on day one.

Why Radicle and not something more familiar? This is worth addressing directly, because Radicle is the least familiar piece of this stack and the choice deserves justification.

A self-hosted Git server — Forgejo, GitLab, Gitea — solves a different problem. It still has a single point of control: whoever runs the server can rewrite history, take the service down, or be compromised. It's an improvement over depending on GitHub specifically, but it doesn't remove the single-point-of-failure property that's the actual concern here.

Signed Git bundles stored on IPFS is a simpler alternative worth considering, and for some teams it might be enough — IPFS gives you content-addressed storage, and a signed bundle gives you provenance for that specific snapshot. But it doesn't give you ongoing collaboration. You'd still need something for issues, pull requests, and code review, and that something would be a separate system with its own trust model — you're back to needing a Layer 1.

Radicle's advantage is that it provides the collaboration layer — issues, patches (Radicle's equivalent of pull requests), code review — and peer-to-peer replication with cryptographic identity, in one system, without a central operator. The honest tradeoffs: Radicle is less mature than GitHub or GitLab, most developers haven't used it, and its long-term maintenance trajectory is something to watch rather than something to take for granted.

This is why Radicle is the collaboration layer and not the trust layer. If Radicle's ecosystem doesn't pan out, the cost of switching collaboration tools is real but bounded — your releases (Layer 3) remain permanent and verifiable regardless of what happens to the collaboration layer, because they don't depend on it. The trust guarantees this document is actually about don't live in Radicle.

Layer 2: Staging and Build Environments — IPFS and Rift

In-progress branches, CI build artifacts, and build environments are stored on IPFS, a content-addressed storage network — meaning files are identified by a hash of their contents, so any change produces a different identifier and tampering is immediately detectable.

For build environments specifically, ClawQL recommends Rift, a tool that uses the same copy-on-write filesystem features your operating system already has (btrfs on Linux, APFS on macOS) to create isolated, instantly-available workspaces:

Rift is early-stage and maintained by a separate project, not by ClawQL. If it doesn't work for your setup, git worktree remains fully supported — everything downstream in this document works with either.

Layer 3: Official Releases — Arweave

This is the core of the system. When you tag a release (v2.1.0, for example), ClawQL bundles everything that matters — source code, container images, Helm charts, a software bill of materials (SBOM), cryptographic signatures, and attestations — and uploads it once to Arweave, a network designed for permanent storage.

Arweave works differently from typical cloud storage: you pay a one-time fee, and the network guarantees the data stays available indefinitely (the pricing model is built around an endowment that funds storage for roughly 200 years). There's no subscription, no renewal, and no "your account was suspended" risk.

The resulting transaction ID becomes the permanent, canonical identifier for that release. Anyone — a person, a CI pipeline, a Kubernetes cluster, an AI agent — can fetch that exact release from any Arweave gateway, indefinitely, and verify it matches what was originally published.

What does this cost? Arweave pricing is roughly $6–$12 per gigabyte, one time, with the price fluctuating along with the AR token. In practice:

For most projects, a release costs under a dollar. Compare that to the cost of responding to an incident caused by a silently-altered release in production — the economics aren't close.

Layer 4: The Glue — clawql-release

A single command-line tool ties everything together:

clawql-release init
clawql-release immutable-volume snapshot [--backend rift|git-worktree|cloudflare|ebs]
clawql-release golden-image build
clawql-release publish --tag v2.1.0
clawql-release verify [tx-id]
clawql-release pull [--rift]

It's open source, written in TypeScript, and works whether or not Rift is available — --backend git-worktree is always a valid fallback.

The Release Manifest

Every upload to Arweave includes a manifest file — a compact JSON document that turns a pile of binary artifacts into something a machine can reason about. Here's a representative example:

{
  "version": "2.1.0",
  "merkleRoot": "8f3a9b...",
  "artifacts": {
    "source": { "cid": "bafy...", "sha256": "a1b2..." },
    "image": { "cid": "bafy...", "sha256": "c3d4...", "ref": "myapp:2.1.0" },
    "sbom": { "cid": "bafy...", "format": "spdx-json" }
  },
  "buildEnvironment": {
    "type": "rift",
    "snapshotId": "snap_8821",
    "parentSnapshotId": "snap_8790",
    "createdAt": "2026-06-01T14:22:00Z"
  },
  "policy": {
    "requireSignatures": ["build-pipeline", "security-review"],
    "canaryPercent": 5,
    "blastRadiusCap": "single-region",
    "rollback": {
      "previousRelease": "tx_7f2a9c...",
      "trigger": "error_rate > 1% for 5min"
    }
  },
  "compatiblePolicyVersion": "1.0"
}

A few things this enables directly:

• Tamper detection. The merkleRoot covers the entire bundle — change one byte of anything, and the root no longer matches. Anyone can verify this without trusting ClawQL or Arweave's operators, only the math.
• Build provenance. The buildEnvironment section records exactly which Rift snapshot (or git worktree commit) produced this release, with a link back to its parent — a verifiable chain of where the code came from.
• Machine-readable policy. A Kubernetes cluster running an admission controller (Kyverno or OPA Gatekeeper) can read the policy block directly and refuse to deploy anything that doesn't meet requireSignatures, or automatically configure a canary rollout at canaryPercent, or know exactly what to roll back to if the rollback.trigger condition fires.
• AI agent consumption. An autonomous agent deploying this release doesn't need to guess what's safe — it reads the policy block and acts accordingly, including knowing how to undo the deployment if something goes wrong.

The manifest schema is versioned (compatiblePolicyVersion) and publicly documented, so auditing a release means auditing against a known, stable schema — not reverse-engineering an opaque format.

Private and Paid Releases

Public releases are uploaded unencrypted, as described above. Private or commercial releases work the same way, with one addition: the bundle is encrypted (using XChaCha20-Poly1305) before upload, and the manifest declares which cryptocurrency wallet address is authorized to decrypt it.

For more complex access conditions — "decrypt after payment," for example — the manifest can reference Lit Protocol, which handles conditional decryption based on on-chain conditions.

What this looks like for an AI agent consuming a paid release:

// Agent encounters a release that requires payment
const manifest = await clawql.verify(txId)

if (manifest.access.paymentRequired) {
  // Pay via x402 (HTTP-native stablecoin micropayment)
  const payment = await x402.pay({
    amount: manifest.access.price, // e.g. "0.50 USDC"
    recipient: manifest.access.wallet,
    resource: txId,
  })

  // Payment receipt is presented to Lit Protocol,
  // which releases the decryption key atomically
  const decryptionKey = await lit.requestKey({
    condition: manifest.access.decryptCondition,
    proof: payment.receipt,
  })

  const bundle = await clawql.decrypt(txId, decryptionKey)
}

The agent pays, receives a key, and decrypts — one atomic flow, no human approval step required for routine, low-value transactions. (Whether that's appropriate without human approval is a policy decision for whoever configures the agent — see the permission-tiering discussion in other ClawQL documentation for how to think about this.)

The Release Workflow in Practice

# One-time setup
rift init
clawql-release init

# Day-to-day development — unchanged
rift create --name agent-fix-42
cd .rifts/agent-fix-42
# ...edit, test, commit as normal...

# When ready to ship
clawql-release immutable-volume snapshot --backend rift --name build-2026-06-01
clawql-release golden-image build      # produces signed images, SBOMs, attestations
clawql-release publish --tag v2.1.0    # uploads to Arweave, updates GitHub mirror banner

# Consuming a release
clawql-release pull --rift             # verifies manifest + signatures, decrypts if needed

Teams not using Rift run the same commands with --backend git-worktree. Nothing about steps 1–2 changes regardless of which backend is used.

Why This Model Holds Up

What Happens When Things Go Wrong

A system built around "permanent and trustworthy" needs to be honest about its own failure modes — otherwise the permanence claim is doing more work than it should.

An Arweave gateway is unreachable. Arweave data is replicated across many independent gateways run by different operators. If one gateway is down, clawql-release pull and verify simply try another. The transaction ID itself doesn't depend on any single gateway — it's a property of the network, not of one server. The practical risk here is closer to "occasionally slower" than "occasionally unavailable."

The price of AR (Arweave's token) changes dramatically. Arweave's storage guarantee is funded by an endowment calculated at upload time, designed to cover storage costs even if the token's value drops substantially afterward — that's the point of the endowment model. The real-world risk isn't zero, since it depends on the endowment model continuing to hold up over decades, which is a long time for any cryptoeconomic assumption. But this risk applies to data already uploaded being maintained — it doesn't affect verification of releases already published, since the transaction ID and content hash don't change regardless of what AR is worth. The practical mitigation: this is a reason to keep the artifacts themselves modest in size (the manifest, signatures, and source are what truly need permanence; large binary blobs can be re-derivable from source plus a recorded build environment, per Layer 3).

A malicious or compromised manifest gets published. This is the most important failure mode to think through, because it's the one an attacker would actually try. Suppose someone with valid signing credentials publishes a release with a manifest that looks legitimate — correct signatures, valid Merkle root — but contains a policy block designed to do something harmful: a rollback.previousRelease pointing to an old, vulnerable version, or a canaryPercent of 100 disguised as 5.

The defenses here are layered, not single-point:

• The manifest schema is public and versioned, so an admission controller can validate that policy values are sane (a canaryPercent outside 0–100, for instance, or a rollback target that doesn't itself verify) before acting on them — independent of whether the signatures check out.
• Signature requirements in policy.requireSignatures should themselves require multiple independent signers for production releases (a "build pipeline" signature alone is necessary but not sufficient) — this is a configuration choice each project makes, and it's worth treating it as seriously as branch protection rules are treated today.
• Because every release is permanent, a malicious release doesn't erase the legitimate history. The previous good release, and its manifest, are still there, still verifiable, and still pullable — "permanent" cuts both ways, but in this case it means rollback targets can't be quietly removed after the fact.
• This is fundamentally a credential-compromise problem, the same as any other supply chain attack — the mitigation is the same as it is everywhere else: protect signing credentials with the same rigor as production deployment credentials, because that's what they now are.

None of this makes a compromised signing key harmless. It does mean the blast radius is bounded and auditable in a way that a quietly-rewritten Git tag is not.

Adoption Path

Nothing here requires an all-or-nothing migration.

1. Day zero: Add clawql-release alongside your existing GitHub workflow. Nothing about how you develop or review code changes.
2. First release: Run clawql-release publish. Your release is now permanent and verifiable. GitHub still works exactly as before — your users won't notice anything different, except that this release can never be silently altered.
3. When it makes sense: Adopt Rift for faster, isolated build environments — especially useful if you're running many AI agents in parallel. Or don't; git worktree works indefinitely.
4. When it makes sense: Move day-to-day collaboration to Radicle for full peer-to-peer operation. GitHub can remain as a mirror for as long as you want.

The only required step is publishing your first release. Everything else is optional hardening that you adopt when it solves a problem you actually have.

For package boundaries and Layer 0 in the platform architecture, see Modularization v2.1. For platform vision and roadmap, see Vision & Roadmap.