Table of Contents

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

Overview

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
• Both surfaces register a single agent-facing tool named froglet to the host (Claude Code, Codex, Cursor, Windsurf, etc.). This is the "tool" exposed to the agent, not a standalone CLI binary — the only shipped binary is froglet-node. A standalone froglet-cli wrapper is on the v0.2 backlog.

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
• The same signed deals can be served over clearnet HTTPS or Tor onion endpoints

[!NOTE] Marketplace, ranking, incentive, and broker policy live above the protocol. Payment rails are adapter-level surfaces for local or self-hosted nodes. Lightning, Stripe, and x402 are the launch adapters in this repo. Only Lightning currently extends into the standardized signed quote/deal/invoice-bundle flow; Stripe and x402 are local runtime settlement adapters. The first-party hosted try.froglet.dev trial is free-only: it uses demo.add as the canonical proof and exposes optional demo.fetch-witness, demo.hash-verify, and demo.notarize follow-ups for stronger evidence. Hosted paid rails are deferred to v0.2.

Components

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

[!TIP] Marketplace integration is part of the public Froglet surface. Runtimes can point at the default public read marketplace with FROGLET_MARKETPLACE_URL; provider auto-registration requires a write-capable marketplace endpoint. See docs/MARKETPLACE.md.

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+ (optional, for MCP/OpenClaw integration tests).

Docker: Docker with Compose v2.

Quick Start

Canonical onboarding lives in docs-site/src/content/docs/learn/index.mdx. Use the repo README for the product and codebase overview, the learn/ docs 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:

curl -fsSL https://raw.githubusercontent.com/armanas/froglet/main/scripts/install.sh | sh
git clone https://github.com/armanas/froglet.git
cd froglet && ./scripts/setup-agent.sh --target claude-code
cd froglet && ./scripts/setup-payment.sh lightning
cd froglet && set -a && . ./.froglet/payment/lightning.env && export FROGLET_HOST_READABLE_CONTROL_TOKEN=true && set +a && docker compose up --build -d

If you only want the signed binary:

curl -fsSL https://raw.githubusercontent.com/armanas/froglet/main/scripts/install.sh | sh

The Compose path and generated host-side agent configs depend on FROGLET_HOST_READABLE_CONTROL_TOKEN=true; the quickstart page carries the full step-by-step explanation, payment-rail variants, and direct froglet-node examples.

# 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.

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
• Local resource inspection and publication via publish_artifact
• Settlement visibility and marketplace-native wrappers
• Status and task polling
• Install planning via plan_install, then command generation via get_install_guide
• Post-install workflow planning via plan_use_case
• Raw compute

MCP Server

External bot hosts and automation systems can use the MCP server instead of the OpenClaw or NemoClaw plugin:

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, use plan_install and get_install_guide before running setup commands through the host shell. After local health is verified, use plan_use_case before implementing consumer, provider, evidence, payments, batch, or GPU workflows. Batch and GPU planning stays truthful: current MCP can plan and verify boundaries. GPU capability advertisement and Docker GPU gating are implemented for self-hosted container services, but true batch fan-out, GPU scheduling, and verified GPU hardware smokes 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:

node integrations/mcp/froglet/server.js

All three launch modes expose the same Froglet control surface over MCP stdio.

For supported local agent targets, generate the exact config file instead of editing JSON or TOML by hand from the cloned repo:

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

Verification

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/
• Reference Froglet node implementation shipped as separable runtime, provider, discovery, and operator binaries
• OpenClaw and NemoClaw bot integration
• 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 Lightning, Stripe, and x402
• Clearnet, Tor, and Nostr-facing adapter support
• 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 rails for Lightning, Stripe, and x402, deferred to v0.2
• 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
• Native deployment adapters for AWS, GCP, OVH, and similar cloud providers
• Zip or archive packaging as a first-class execution submission format
• First-party hosted control-plane operations and runbooks

[!WARNING] Execution hardening is not uniform across all runtimes. The strongest isolation paths are Wasm sandbox execution and confidential/TEE profiles; Python and OCI/container execution inherit host or container isolation characteristics.

Documentation

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