cargo run -p froglet-verify -- conformance/kernel_v1.json

Table of Contents

• Overview
• Product Model
• Components
• Quick Start
• Bot Surfaces
• Verification
• Current Scope
• Documentation

Overview

The current product candidate starts with “Make this catalog usable by another agent.” Codex or Claude Code can prepare selected JSON, typed CSV, or SQLite data, or a small Wasm function; run a local example; ask for exact publication approval; and return a provider/service share link. Native setup preserves existing agent settings. Recipients use the same native integration without npm.

See the publishing workflow and the qualification gates. This is an uncommitted candidate: clean-machine agent tests, the real public relay journey, and first-time-user acceptance remain release gates. Supported targets are Apple Silicon macOS and Linux x86_64/arm64. The host must stay online.

Froglet gives one signed economic primitive for three product shapes:

The primary bot-facing integration surfaces are intentionally simple:

• One OpenClaw/NemoClaw plugin id: froglet (at integrations/openclaw/froglet/)
• One MCP server under integrations/mcp/froglet/, published as froglet-mcp for npx froglet-mcp, plus a dependency-minimal native bridge in froglet-node mcp
• Both surfaces register a single agent-facing tool named froglet to the host (Claude Code, Codex, Cursor, Windsurf, etc.). The headline action is two-step marketplace_publish: the first call is a non-mutating plan, and the second must carry the exact approved consent_hash. Both native and JavaScript adapters delegate to the same Rust publication module and provider-control contract.
• The froglet-node binary is both the daemon (running as a provider) and the author CLI (froglet-node init / build / publish / whoami, prepare-service, invoke, doctor, and check-updates). status --open --json returns a short-lived read-only local status URL.

Bots should be able to create small scriptable services directly, validate them locally, and publish them without starting from OCI images. OCI containers remain a supported packaging and deployment path.

Product Model

• Any Froglet node can publish resources and invoke remote resources
• Published resources are execution bindings backed by bot-authored projects, explicit source, or prebuilt artifacts
• Easy bot authoring and local checking of scriptable services is a core product requirement
• Identity is first-class in signed artifacts
• Clearnet HTTPS, outbound relay HTTPS, and Tor v3 onion transport are supported registration paths for self-hosted providers. Bootstrap plans the official relay URL and suffix by default but keeps them dormant; publication fails closed until an exact durable grant makes the endpoint ready. Planned configuration is not a claim that its public operator service is deployed.

Components

Product-wise, Froglet is one node that can both provide and consume. The reference implementation exposes these binaries:

Prerequisites

Binary install (quickest): curl, tar, sha256sum (Linux) or shasum (macOS). Supported: Linux x86_64/arm64, macOS arm64.

Build from source: Rust 1.91+, Python 3.12+ (for tests), Node 18+ with npm (for Claude Code/Codex MCP setup and integration tests).

Docker (optional fallback/contributor stack): Docker with Compose v2.

Quick Start

Canonical onboarding lives in docs-site/src/content/docs/docs.mdx (the learn/ index remains as a legacy route). Use the repo README for the product and codebase overview, the docs-site manual for the public launch path, and docs/ for specs, operator notes, and integration reference.

The public launch story still has exactly two entry points:

1. Try In Cloud

• Start with docs-site/src/content/docs/learn/cloud-trial.mdx
• Contract reference: docs/HOSTED_TRIAL.md
• Session tokens on try.froglet.dev authorize only POST /v1/runtime/deals and GET /v1/runtime/deals/{deal_id}
• try.froglet.dev is the only public hosted-trial ingress; ai.froglet.dev does not expose session minting or hosted demo deal routes directly
• The hosted demo catalog has five free services: demo.add, demo.echo, demo.fetch-witness, demo.hash-verify, and demo.notarize
• demo.add is the canonical discover → deal → result → receipt proof; witness/hash/notarize flows are optional higher-signal follow-ups
• The hosted trial still does not prove paid rails, persistent identity, service publication, marketplace depth, or general runtime access

2. Run Locally

• Start with docs-site/src/content/docs/learn/quickstart.mdx
• Then use docs-site/src/content/docs/learn/agents.mdx and docs-site/src/content/docs/learn/payment-rails.mdx
• Self-host and operator follow-ons live in docs/DOCKER.md, docs/GCP_SINGLE_VM.md, and docs/MARKETPLACE.md

Minimal full local stack from zero:

set -eu
repo=armanas/froglet
metadata="$(mktemp "${TMPDIR:-/tmp}/froglet-release.XXXXXX")"
bootstrap="$(mktemp "${TMPDIR:-/tmp}/froglet-agent-bootstrap.XXXXXX")"
release_url="$(curl -fsSL --proto '=https' --proto-redir '=https' --tlsv1.2 -o /dev/null -w '%{url_effective}' "https://github.com/$repo/releases/latest")"
tag="${release_url%/}"; tag="${tag##*/}"
printf '%s' "$tag" | grep -Eq '^v[0-9A-Za-z][0-9A-Za-z.+-]*$'
curl -fsSL --proto '=https' --proto-redir '=https' --tlsv1.2 -H 'Accept: application/vnd.github+json' \
  -H 'X-GitHub-Api-Version: 2026-03-10' \
  "https://api.github.com/repos/$repo/releases/tags/$tag" -o "$metadata"
[ "$(sed -n 's/^  "immutable": \([a-z]*\),*$/\1/p' "$metadata")" = true ]
[ "$(sed -n 's/^  "tag_name": "\([^"]*\)",*$/\1/p' "$metadata")" = "$tag" ]
asset_record="$(awk '
  /^    \{/ { in_asset=1; name=digest=state=""; next }
  in_asset && /^      "name":/ { v=$0; sub(/^      "name": "/,"",v); sub(/",*$/,"",v); name=v }
  in_asset && /^      "digest":/ { v=$0; sub(/^      "digest": "/,"",v); sub(/",*$/,"",v); digest=v }
  in_asset && /^      "state":/ { v=$0; sub(/^      "state": "/,"",v); sub(/",*$/,"",v); state=v }
  in_asset && /^    \},*$/ { if (name=="agent-bootstrap.sh") print digest "|" state; in_asset=0 }
' "$metadata")"
[ "$(printf '%s\n' "$asset_record" | sed '/^$/d' | wc -l | tr -d ' ')" = 1 ]
bootstrap_digest="${asset_record%%|*}"; asset_state="${asset_record#*|}"
[ "$asset_state" = uploaded ]
printf '%s' "$bootstrap_digest" | grep -Eq '^sha256:[0-9a-f]{64}$'
bootstrap_digest="${bootstrap_digest#sha256:}"
curl -fsSL --proto '=https' --proto-redir '=https' --tlsv1.2 \
  "https://github.com/$repo/releases/download/$tag/agent-bootstrap.sh" -o "$bootstrap"
if command -v sha256sum >/dev/null 2>&1; then actual="$(sha256sum "$bootstrap" | awk '{print $1}')";
elif command -v shasum >/dev/null 2>&1; then actual="$(shasum -a 256 "$bootstrap" | awk '{print $1}')";
else actual="$(openssl dgst -sha256 "$bootstrap" | sed 's/^.*= //')"; fi
[ "$actual" = "$bootstrap_digest" ]
chmod 0700 "$bootstrap"
VERSION="$tag" sh "$bootstrap" plan
# Show the complete plan and wait for approval. Then copy its exact hash:
VERSION="$tag" sh "$bootstrap" execute '<install_approval_hash>'
rm -f "$bootstrap" "$metadata"

plan is the safe default and writes nothing outside its temporary workspace. It resolves the immutable release, verified manifest and target-platform binary asset digests, exact bootstrap/install/configuration script digests, persistent paths, and service-manager impact into one canonical approval hash. execute recomputes that contract and stops before any persistent write if the release, script bytes, profile, paths, or supplied hash changed.

After approval, the agent bootstrap verifies a Release Bundle, installs the checksum-verified froglet-node, starts the native dual-role service through launchd/systemd, writes native MCP config, and returns only after health plus a non-seeding MCP status proof and a transient read-only data proof that is confirmed-unpublished. The proof first requires an empty active-offer feed and no lifecycle for its exact service ID, records a private cleanup intent before publishing, and removes both its offer and authoring directory only after an empty-feed check. A failed proof attempts exact unpublish while the service is still live and preserves a recovery marker if cleanup cannot be proved. A digest-pinned dual-role GHCR image is the fallback when native service management is unavailable.

The approval plan includes the official relay endpoint and DNS suffix by default. This is dormant configuration: it derives an exact planned HTTPS URL but opens no WSS connection and exposes no service before an exact durable publication grant. Set both FROGLET_RELAY_URL='' and FROGLET_RELAY_PUBLIC_SUFFIX='' before plan to opt out. The first-party DNS/TLS endpoint is not yet live-proven, so relay publication remains an explicit external gate rather than an install success claim. See docs/RELAY.md. The implementation/evidence matrix in docs/AGENT_FIRST_PUBLICATION_PLAN.md tracks which clean-host and external gates remain open.

From a trusted checkout, run the disposable-host proof with bash scripts/fresh_host_quickstart_smoke.sh.

The lower-level scripts/install.sh is an internal release-bundle installer; agents should use the approval-gated bootstrap above.

Source-checkout Compose and generated host-side agent configs depend on FROGLET_HOST_READABLE_CONTROL_TOKEN=true; the default user path is the no-clone /agent bootstrap. The quickstart page carries the step-by-step MCP-first explanation, payment-rail decisions, Tor registration, managed subdomains, and contributor/source-mode fallbacks.

# Provider node
FROGLET_NODE_ROLE=provider \
FROGLET_PRICE_EXEC_WASM=10 \
FROGLET_PAYMENT_BACKEND=lightning \
FROGLET_LIGHTNING_MODE=mock \
cargo run -p froglet --bin froglet-node

# Runtime node
FROGLET_NODE_ROLE=runtime \
FROGLET_PAYMENT_BACKEND=lightning \
FROGLET_LIGHTNING_MODE=mock \
cargo run -p froglet --bin froglet-node

Bot Surfaces

OpenClaw, NemoClaw, and MCP-compatible hosts are the primary bot-facing surfaces today. Distribution status and marketplace/plugin ordering live in PLUGIN_DISTRIBUTION.md.

OpenClaw & NemoClaw

Use the shared plugin package in integrations/openclaw/froglet. Current OpenClaw plugin install/inspect and gateway invocation require Node.js 22.14.0 or newer. Gateway-mediated local actions should launch with FROGLET_PROVIDER_AUTH_TOKEN_PATH and FROGLET_RUNTIME_AUTH_TOKEN_PATH pointing at the local data/runtime/ token files.

The generated local OpenClaw config uses the split provider/runtime keys above. Legacy baseUrl and authTokenPath remain supported for single-surface configs such as the checked-in NemoClaw examples.

The one froglet tool covers:

• Service discovery and invocation
• Agent-grade service publication via marketplace_publish
• Local artifact publication via publish_artifact
• Settlement visibility and current marketplace wrappers
• Status and task polling
• Exact install approval via non-mutating plan_install, then approved command generation via get_install_guide
• Post-install workflow planning via plan_use_case
• Raw compute

MCP: native default and JavaScript compatibility

The no-clone native install configures the released binary directly:

froglet-node mcp

This bridge needs no Node.js runtime. Its deliberately focused froglet tool supports status, invoke_service, two-step marketplace_publish, and publication status/logs/pause/resume/rollback/ confirmed-unpublish. Durable cloud-adapter work is separately visible through managed-operation status, confirmed reconciliation, and confirmed compensation. local_proof is available only when an operator has deliberately enabled the bundled demo catalog; clean installation does not. Publication delegates to the same canonical project loader, consent logic, and provider-control API as the CLI.

The JavaScript MCP package is the broader compatibility and contributor surface for discovery, settlement, install planning, raw compute, and existing host integrations:

npx froglet-mcp

The npm package defaults to FROGLET_PROFILE=local, with provider/runtime URLs pointing at http://127.0.0.1:8080 and http://127.0.0.1:8081. Agents should call status first. If the local node or token files are missing, call plan_install, show its immutable release tag, manifest/bootstrap SHA-256 values, persistent paths, process-manager impact, and exact command preview, then wait for approval. Only after approval, pass the returned release_tag and install_approval_hash unchanged to get_install_guide and run its verified-temp-file command through the host shell. After local health is verified, use plan_use_case before implementing consumer, provider, evidence, payments, batch, or GPU workflows. The native froglet-node mcp bridge also prepares fixed HTTPS JSON services, issues expiring invitations into private files, and controls durable admission limits. See bounded HTTP services and invitations. Payments remain a separate operator decision. Public marketplace canaries currently require anonymous access; private/invite services use direct provider invocation.

GPU execution is currently unavailable: the reference OCI worker does not attach or account for devices. GPU capabilities are not advertised and GPU requests fail explicitly. Earlier Docker/GCP hardware proof does not qualify this worker. Batch fan-out, GPU scheduling and general storage remain separate work. The public no-install proof remains the HTTP flow at https://froglet.dev/llms.txt; it is not an installed MCP action.

For a local node, use the local profile:

FROGLET_PROFILE=local \
FROGLET_PROVIDER_URL=http://127.0.0.1:8080 \
FROGLET_RUNTIME_URL=http://127.0.0.1:8081 \
FROGLET_PROVIDER_AUTH_TOKEN_PATH=/absolute/path/to/froglet/data/runtime/froglet-control.token \
FROGLET_RUNTIME_AUTH_TOKEN_PATH=/absolute/path/to/froglet/data/runtime/auth.token \
  npx froglet-mcp

From a source checkout, the same server can be run directly:

npm ci --prefix integrations/mcp/froglet
node integrations/mcp/froglet/server.js

The npm, source-checkout, and digest-pinned MCP-image modes expose the broader JavaScript surface over MCP stdio. The native mode exposes the smaller dependency-free publication/lifecycle surface above; it does not claim action parity with JavaScript.

For normal users, the /agent bootstrap writes the local MCP config without a repo clone. From a source checkout, contributors can still generate the exact config file instead of editing JSON or TOML by hand:

cd froglet && ./scripts/setup-agent.sh --target claude-code
cd froglet && ./scripts/setup-agent.sh --target codex

Portable Managed Hosting and OCI Isolation

froglet-service/v4 expresses managed hosting as a provider-neutral target/profile. It does not contain AWS regions, Lightsail names, Fly apps, ECR repositories, or cloud SDK types. The sibling Managed Deployment operator implements the corresponding portable desired-state lifecycle through the current Lightsail compatibility adapter or generic SSH + OCI adapter and returns the same normalized result shape. Publish-engine-to-operator wiring and credentialed live canaries remain separate open gates.

V3 manifests remain readable. hosting.default = "fly" and hosting.fly.* are deprecated compatibility inputs only; new authoring uses v4 managed, and provider selection belongs in operator-owned adapter configuration. See docs/PUBLICATION_CONTRACT.md.

Arbitrary OCI execution does not give the Froglet Node a Docker/Podman socket. The node sends a digest-only, bounded, capability-reduced request to an authenticated worker endpoint configured by FROGLET_OCI_WORKER_URL and FROGLET_OCI_WORKER_TOKEN_PATH. The reference OCI worker owns rootless engine access and defaults to read-only, non-root, no-network execution. With no worker configured, OCI execution fails closed.

Verification

Verifying artifact chains (what a counterparty does)

froglet-verify is a standalone offline verifier: no node, no network, no account, and no clock unless you supply one. Point it at a chain and it checks every envelope signature, every per-artifact semantic rule, and every hash link between artifacts.

cargo run -p froglet-verify -- conformance/kernel_v1.json

It accepts a single artifact, a JSON array, a /v1/feed page, or a conformance fixture, from a file or stdin; --json emits a machine-readable report and --now <unix> turns on expiry checks. Exit codes: 0 valid, 1 invalid, 2 usage error.

The Rust facade, browser WASM build, and in-repo Rust conformance runners share the froglet-protocol implementation. python/froglet-verify is independently implemented and checks the same public vectors. Multiple Rust runners exercise distribution paths; they do not provide implementation diversity. See conformance/README.md for what a conforming runner must assert, and docs/SPEC.md for the normative rules.

Build and repo checks

Targeted checks:

cargo check -q
cargo test -q --lib
node --check integrations/openclaw/froglet/index.js
node --check integrations/openclaw/froglet/scripts/doctor.mjs
node --test integrations/openclaw/froglet/test/plugin.test.js \
  integrations/openclaw/froglet/test/config-profiles.test.mjs \
  integrations/openclaw/froglet/test/doctor.test.mjs \
  integrations/openclaw/froglet/test/froglet-client.test.mjs
npm run check:mcp
npm run test:mcp

Full repo checks:

./scripts/strict_checks.sh

FROGLET_RUN_COMPOSE_SMOKE=1 ./scripts/strict_checks.sh

node integrations/openclaw/froglet/test/compose-smoke.mjs
node integrations/mcp/froglet/test/compose-smoke.mjs

Current Scope

In this repo now:

• Protocol and supporting specifications under docs/ and conformance/ — stability guarantees in docs/VERSIONING.md; to build a second implementation in another language, start from the canonical test vectors in conformance/kernel_v1.json (guide: froglet.dev/spec/conformance)
• Reference Froglet node implementation: a single froglet-node binary serving split provider and runtime planes (published as froglet-provider and froglet-runtime container images)
• OpenClaw source-plugin integration and shared NemoClaw plugin code, with host-specific verification status documented separately
• Native dependency-minimal MCP bridge plus the broader JavaScript MCP server for external agent hosts and automations
• Python-backed helpers and tests for the public node and protocol surface
• Local project authoring, build, test, and publish flows for bot-authored services
• Direct artifact publication for prebuilt Wasm and OCI-backed profiles
• Reference execution profiles for Wasm, Python, container, and confidential execution paths
• Local/self-hosted reference settlement support for operator-controlled Lightning, Stripe, and x402
• Clearnet and outbound relay transports plus optional self-hosted Tor and Nostr-facing adapter support; live public relay readiness is an external deployment gate, not inferred from the client implementation
• Tests, validation scripts, and release docs for the public repo surface
• Public-facing self-host documentation and examples

Later or separately deployed:

• First-party hosted paid rail claims for Lightning and Stripe, pending public live transcripts; hosted x402 remains desirable but non-blocking
• The hosted try.froglet.dev gateway's private operational lifecycle
• Higher-layer marketplace ranking, reputation, and policy services
• Long-running batch orchestration, which remains out of scope for the current v1 runtime surface
• Credentialed live proof for the provider-neutral Lightsail and generic SSH + OCI Managed Deployment adapters maintained in froglet-services
• Additional provisioning adapters for GCP, OVH, and similar providers when demand justifies them; no new provider enum belongs in the manifest
• Zip or archive packaging as a first-class execution submission format
• First-party hosted control-plane operations and runbooks

Documentation

First-party hosted deployment tooling and operator runbooks are maintained separately from the public protocol and self-host docs in this repo.