{
"markdown": "\n\n# Froglet\n\n**A protocol and node for a bot economy.**\n\n[](https://github.com/armanas/froglet/actions/workflows/ci.yml)\n[](https://github.com/armanas/froglet/actions/workflows/release.yml)\n[](LICENSE)\n[](https://www.rust-lang.org/)\n[](https://doc.rust-lang.org/edition-guide/)\n[](https://github.com/armanas/froglet/pkgs/container/froglet-provider)\n\nLets bots create, publish, discover, buy, sell, and compose remote resources for value.\n\nMaintained by [Armanas Povilionis-Muradian](https://armanas.dev).\n\n
\n\n---\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Product Model](#product-model)\n- [Components](#components)\n- [Quick Start](#quick-start)\n- [Bot Surfaces](#bot-surfaces)\n- [Verification](#verification)\n- [Current Scope](#current-scope)\n- [Documentation](#documentation)\n\n---\n\n## Overview\n\nFroglet gives one signed economic primitive for three product shapes:\n\n| Shape | Description |\n|---|---|\n| **Named Services** | Discoverable, published service endpoints |\n| **Data-Backed Services** | Services backed by bot-authored data or projects |\n| **Open-Ended Compute** | Raw compute targeted via `provider_id` or `provider_url` |\n\nThe primary bot-facing integration surfaces are intentionally simple:\n\n- One OpenClaw/NemoClaw plugin id: `froglet` (at `integrations/openclaw/froglet/`)\n- One MCP server under `integrations/mcp/froglet/`, published as\n `froglet-mcp` for `npx froglet-mcp`\n- Both surfaces register a single agent-facing tool named `froglet` to\n the host (Claude Code, Codex, Cursor, Windsurf, etc.). The headline\n action is `marketplace_publish`: one MCP call turns a user prompt\n (\"publish a service that does X\") into a live marketplace offer in\n seconds. Behind the scenes it shells out to `froglet-node publish`,\n the CLI subcommand that humans use for the same flow. One pipeline,\n two surfaces, one source of truth.\n- The `froglet-node` binary is both the daemon (running as a provider)\n and the author CLI (`froglet-node init` / `build` / `publish` /\n `whoami`). A separate `froglet` CLI binary is deferred to v0.3+; the\n split is unnecessary today.\n\nBots should be able to create small scriptable services directly, validate them\nlocally, and publish them without starting from OCI images.\nOCI containers remain a supported packaging and deployment path.\n\n---\n\n## Product Model\n\n- Any Froglet node can publish resources and invoke remote resources\n- Published resources are execution bindings backed by bot-authored projects,\n explicit source, or prebuilt artifacts\n- Easy bot authoring and local checking of scriptable services is a core\n product requirement\n- Identity is first-class in signed artifacts\n- Clearnet HTTPS and Tor v3 onion transport are supported registration paths\n for self-hosted providers. The first-party hosted MVP does not publish an\n onion endpoint until that endpoint is separately deployed and verified.\n\n> [!NOTE]\n> Marketplace, ranking, incentive, and broker policy live above the protocol.\n> Payment rails are adapter-level surfaces for local or self-hosted operators,\n> not normal buyer onboarding.\n> Lightning, Stripe, and x402 are the launch adapters in this repo. Only\n> Lightning currently extends into the standardized signed\n> quote/deal/invoice-bundle flow; Stripe and x402 are local runtime settlement\n> adapters. The first-party hosted `try.froglet.dev` trial is free-only: it\n> uses `demo.add` as the canonical proof and exposes optional\n> `demo.fetch-witness`, `demo.hash-verify`, and `demo.notarize` follow-ups for\n> stronger evidence. Hosted paid rails must not be claimed live until Lightning\n> and Stripe have public payment transcripts, and users should not be asked to\n> manage LND channels or payment secrets just to try Froglet.\n\n\nDiscovery & Compute model
\n\n- Named services and data services are discovered through discovery\n- Open-ended compute uses the provider's direct compute offer via\n `run_compute`, targeted with `provider_id` or `provider_url`\n- Publication and bootstrap adapters may include Nostr-style publication\n without making any single relay or network the kernel source of truth\n\n \n\n---\n\n## Components\n\nProduct-wise, Froglet is one node that can both provide and consume.\nThe reference implementation exposes these binaries:\n\n| Binary | Purpose | Default Port |\n|---|---|---|\n| `froglet-node` | Provider and/or runtime node (role configured via env) | `8080` / `8081` |\n\n> [!TIP]\n> Marketplace integration is part of the public Froglet surface. Runtimes can\n> point at the default public marketplace with `FROGLET_MARKETPLACE_URL`;\n> providers can self-register there after exposing a public HTTPS URL, Tor v3\n> onion URL, or claimed `*.providers.froglet.dev` hostname. See\n> [docs/MARKETPLACE.md](docs/MARKETPLACE.md).\n\n---\n\n## Prerequisites\n\n**Binary install (quickest):** curl, tar, sha256sum (Linux) or shasum (macOS).\nSupported: Linux x86_64/arm64, macOS arm64.\n\n**Build from source:** Rust 1.91+, Python 3.12+ (for tests), Node 18+ with npm\n(for Claude Code/Codex MCP setup and integration tests).\n\n**Docker:** Docker with Compose v2.\n\n## Quick Start\n\nCanonical onboarding lives in\n[docs-site/src/content/docs/docs.mdx](docs-site/src/content/docs/docs.mdx)\n(the `learn/` index remains as a legacy route).\nUse the repo README for the product and codebase overview, the docs-site\nmanual for the public launch path, and `docs/` for specs, operator notes, and\nintegration reference.\n\nThe public launch story still has exactly two entry points:\n\n### 1. Try In Cloud\n\n- Start with\n [docs-site/src/content/docs/learn/cloud-trial.mdx](docs-site/src/content/docs/learn/cloud-trial.mdx)\n- Contract reference: [docs/HOSTED_TRIAL.md](docs/HOSTED_TRIAL.md)\n- Session tokens on `try.froglet.dev` authorize only\n `POST /v1/runtime/deals` and `GET /v1/runtime/deals/{deal_id}`\n- `try.froglet.dev` is the only public hosted-trial ingress; `ai.froglet.dev`\n does not expose session minting or hosted demo deal routes directly\n- The hosted demo catalog has five free services: `demo.add`, `demo.echo`,\n `demo.fetch-witness`, `demo.hash-verify`, and `demo.notarize`\n- `demo.add` is the canonical discover → deal → result → receipt proof;\n witness/hash/notarize flows are optional higher-signal follow-ups\n- The hosted trial still does not prove paid rails, persistent identity,\n service publication, marketplace depth, or general runtime access\n\n### 2. Run Locally\n\n- Start with\n [docs-site/src/content/docs/learn/quickstart.mdx](docs-site/src/content/docs/learn/quickstart.mdx)\n- Then use\n [docs-site/src/content/docs/learn/agents.mdx](docs-site/src/content/docs/learn/agents.mdx)\n and\n [docs-site/src/content/docs/learn/payment-rails.mdx](docs-site/src/content/docs/learn/payment-rails.mdx)\n- Self-host and operator follow-ons live in [docs/DOCKER.md](docs/DOCKER.md),\n [docs/GCP_SINGLE_VM.md](docs/GCP_SINGLE_VM.md), and\n [docs/MARKETPLACE.md](docs/MARKETPLACE.md)\n\nMinimal full local stack from zero:\n\n```bash\ncurl -fsSL https://froglet.dev/agent | bash\n```\n\nThe agent bootstrap installs the signed `froglet-node`, starts provider/runtime\nfrom published GHCR images under `~/.froglet/agent`, writes MCP config, and\nleaves payments/public registration for the installed `froglet-mcp` flow after\nlocal health checks pass.\n\nDisposable-host proof runner:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/armanas/froglet/main/scripts/fresh_host_quickstart_smoke.sh | bash\n```\n\nIf you only want the signed binary:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/armanas/froglet/main/scripts/install.sh | sh\n```\n\nSource-checkout Compose and generated host-side agent configs depend on\n`FROGLET_HOST_READABLE_CONTROL_TOKEN=true`; the default user path is the\nno-clone `/agent` bootstrap. The quickstart page carries the step-by-step\nMCP-first explanation, payment-rail decisions, Tor registration, managed\nsubdomains, and contributor/source-mode fallbacks.\n\n\nRunning binaries directly (without Compose)
\n\n```bash\n# Provider node\nFROGLET_NODE_ROLE=provider \\\nFROGLET_PRICE_EXEC_WASM=10 \\\nFROGLET_PAYMENT_BACKEND=lightning \\\nFROGLET_LIGHTNING_MODE=mock \\\ncargo run -p froglet --bin froglet-node\n```\n\n```bash\n# Runtime node\nFROGLET_NODE_ROLE=runtime \\\nFROGLET_PAYMENT_BACKEND=lightning \\\nFROGLET_LIGHTNING_MODE=mock \\\ncargo run -p froglet --bin froglet-node\n```\n\nThe normal model is one node running both provider and runtime roles\n(`FROGLET_NODE_ROLE=dual`), so it can publish local resources and invoke\nremote ones.\n\nSet `FROGLET_MARKETPLACE_URL` on runtime nodes to search through an external\nmarketplace. Providers can self-register with the default public marketplace\nafter they advertise a matching public HTTPS origin, Tor v3 onion URL, or\nclaimed `*.providers.froglet.dev` hostname.\n\n \n\n---\n\n## Bot Surfaces\n\nOpenClaw, NemoClaw, and MCP-compatible hosts are the primary bot-facing\nsurfaces today. Distribution status and marketplace/plugin ordering live in\n[PLUGIN_DISTRIBUTION.md](docs/PLUGIN_DISTRIBUTION.md).\n\n### OpenClaw & NemoClaw\n\nUse the shared plugin package in\n[integrations/openclaw/froglet](integrations/openclaw/froglet).\nCurrent OpenClaw plugin install/inspect and gateway invocation require\nNode.js `22.14.0` or newer. Gateway-mediated local actions should launch with\n`FROGLET_PROVIDER_AUTH_TOKEN_PATH` and `FROGLET_RUNTIME_AUTH_TOKEN_PATH`\npointing at the local `data/runtime/` token files.\n\n\nConfiguration keys
\n\n| Key | Purpose |\n|---|---|\n| `hostProduct` | Target host product |\n| `providerUrl` | Provider/public API base URL |\n| `runtimeUrl` | Runtime API base URL |\n| `providerAuthTokenPath` | Path to the provider control token |\n| `runtimeAuthTokenPath` | Path to the runtime auth token |\n| `baseUrl` | Legacy single-surface fallback URL |\n| `authTokenPath` | Legacy single-token fallback path |\n| `requestTimeoutMs` | HTTP request timeout |\n| `defaultSearchLimit` | Default discovery result limit |\n| `maxSearchLimit` | Maximum discovery result limit |\n\n \n\nThe generated local OpenClaw config uses the split provider/runtime keys above.\nLegacy `baseUrl` and `authTokenPath` remain supported for single-surface\nconfigs such as the checked-in NemoClaw examples.\n\nThe one `froglet` tool covers:\n\n- Service discovery and invocation\n- Agent-grade service publication via `marketplace_publish`\n- Local artifact publication via `publish_artifact`\n- Settlement visibility and current marketplace wrappers\n- Status and task polling\n- Install planning via `plan_install`, then command generation via `get_install_guide`\n- Post-install workflow planning via `plan_use_case`\n- Raw compute\n\n\nImportant behavior notes
\n\n- `summary` is metadata only; it does not generate code\n- `publish_artifact` is the current local publication path\n- `run_compute` is the low-level path for open-ended compute and should include\n `provider_id` or `provider_url`\n- Project authoring, log tailing, and node restart are not part of the current\n public tool API\n\n \n\n### MCP Server\n\nExternal bot hosts and automation systems can use the MCP server instead of\nthe OpenClaw or NemoClaw plugin:\n\n```bash\nnpx froglet-mcp\n```\n\nThe npm package defaults to `FROGLET_PROFILE=local`, with provider/runtime URLs\npointing at `http://127.0.0.1:8080` and `http://127.0.0.1:8081`. Agents should\ncall `status` first. If the local node or token files are missing, use\n`plan_install` and `get_install_guide` before running setup commands through\nthe host shell. After local health is verified, use `plan_use_case` before\nimplementing consumer, provider, evidence, payments, batch, or GPU workflows.\nBatch and GPU planning stays truthful: current MCP can plan and verify\nboundaries. GPU capability advertisement, generic-compute offer metadata,\nDocker `--gpus all` gating, no-CPU-fallback errors, and one self-hosted GCP T4\ncontainer workload with a signed receipt are verified. True batch fan-out, GPU\nscheduling/provider selection, marketplace GPU routing, and production capacity\nmanagement remain separate work. The public no-install proof remains the HTTP\nflow at `https://froglet.dev/llms.txt`; it is not an installed MCP action.\n\nFor a local node, use the local profile:\n\n```bash\nFROGLET_PROFILE=local \\\nFROGLET_PROVIDER_URL=http://127.0.0.1:8080 \\\nFROGLET_RUNTIME_URL=http://127.0.0.1:8081 \\\nFROGLET_PROVIDER_AUTH_TOKEN_PATH=/absolute/path/to/froglet/data/runtime/froglet-control.token \\\nFROGLET_RUNTIME_AUTH_TOKEN_PATH=/absolute/path/to/froglet/data/runtime/auth.token \\\n npx froglet-mcp\n```\n\nFrom a source checkout, the same server can be run directly:\n\n```bash\nnpm ci --prefix integrations/mcp/froglet\nnode integrations/mcp/froglet/server.js\n```\n\nAll three launch modes expose the same Froglet control surface over MCP stdio.\n\nFor normal users, the `/agent` bootstrap writes the local MCP config without a\nrepo clone. From a source checkout, contributors can still generate the exact\nconfig file instead of editing JSON or TOML by hand:\n\n```bash\ncd froglet && ./scripts/setup-agent.sh --target claude-code\ncd froglet && ./scripts/setup-agent.sh --target codex\n```\n\n---\n\n## Verification\n\n**Targeted checks:**\n\n```bash\ncargo check -q\ncargo test -q --lib\nnode --check integrations/openclaw/froglet/index.js\nnode --check integrations/openclaw/froglet/scripts/doctor.mjs\nnode --test integrations/openclaw/froglet/test/plugin.test.js \\\n integrations/openclaw/froglet/test/config-profiles.test.mjs \\\n integrations/openclaw/froglet/test/doctor.test.mjs \\\n integrations/openclaw/froglet/test/froglet-client.test.mjs\nnpm run check:mcp\nnpm run test:mcp\n```\n\n**Full repo checks:**\n\n```bash\n./scripts/strict_checks.sh\n```\n\n\nCompose-backed smoke tests
\n\nOptional compose-backed bot-surface smoke coverage:\n\n```bash\nFROGLET_RUN_COMPOSE_SMOKE=1 ./scripts/strict_checks.sh\n```\n\nManual compose-backed smoke commands:\n\n```bash\nnode integrations/openclaw/froglet/test/compose-smoke.mjs\nnode integrations/mcp/froglet/test/compose-smoke.mjs\n```\n\n \n\n---\n\n## Current Scope\n\n**In this repo now:**\n\n- Protocol and supporting specifications under `docs/` and `conformance/` —\n stability guarantees in [docs/VERSIONING.md](docs/VERSIONING.md); to build a\n second implementation in another language, start from the canonical test\n vectors in [`conformance/kernel_v1.json`](conformance/kernel_v1.json) (guide:\n [froglet.dev/spec/conformance](https://froglet.dev/spec/conformance/))\n- Reference Froglet node implementation: a single `froglet-node` binary\n serving split provider and runtime planes (published as `froglet-provider`\n and `froglet-runtime` container images)\n- OpenClaw source-plugin integration and shared NemoClaw plugin code, with\n host-specific verification status documented separately\n- MCP server for external agent hosts and automations\n- Python-backed helpers and tests for the public node and protocol surface\n- Local project authoring, build, test, and publish flows for bot-authored\n services\n- Direct artifact publication for prebuilt Wasm and OCI-backed profiles\n- Reference execution profiles for Wasm, Python, container, and confidential\n execution paths\n- Local/self-hosted reference settlement support for operator-controlled\n Lightning, Stripe, and x402\n- Clearnet launch transport plus optional self-hosted Tor and Nostr-facing\n adapter support\n- Tests, validation scripts, and release docs for the public repo surface\n- Public-facing self-host documentation and examples\n\n**Later or separately deployed:**\n\n- First-party hosted paid rail claims for Lightning and Stripe, pending public\n live transcripts; hosted x402 remains desirable but non-blocking\n- The hosted `try.froglet.dev` gateway's private operational lifecycle\n- Higher-layer marketplace ranking, reputation, and policy services\n- Long-running batch orchestration, which remains out of scope for the current\n v1 runtime surface\n- Native deployment adapters for AWS, GCP, OVH, and similar cloud providers\n- Zip or archive packaging as a first-class execution submission format\n- First-party hosted control-plane operations and runbooks\n\n> [!WARNING]\n> Execution hardening is not uniform across all runtimes.\n> The strongest isolation paths are Wasm sandbox execution and confidential/TEE\n> profiles; Python and OCI/container execution inherit host or container\n> isolation characteristics.\n\n---\n\n## Documentation\n\n| Document | Topic |\n|---|---|\n| [docs-site/src/content/docs/docs.mdx](docs-site/src/content/docs/docs.mdx) | Canonical onboarding manual for the public launch story |\n| [docs-site/src/content/docs/learn/cloud-trial.mdx](docs-site/src/content/docs/learn/cloud-trial.mdx) | Hosted trial walkthrough and contract |\n| [docs-site/src/content/docs/learn/quickstart.mdx](docs-site/src/content/docs/learn/quickstart.mdx) | Local self-host quickstart |\n| [docs/README.md](docs/README.md) | Reference-doc map for specs, operations, and integrations |\n| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | System architecture overview |\n| [ADAPTERS.md](docs/ADAPTERS.md) | Payment and network adapters |\n| [RUNTIME.md](docs/RUNTIME.md) | Runtime internals |\n| [SERVICE_BINDING.md](docs/SERVICE_BINDING.md) | Service binding model |\n| [IDENTITY_ATTESTATION.md](docs/IDENTITY_ATTESTATION.md) | Optional DNS + OAuth identity bindings for Froglet keys |\n| [PLUGIN_DISTRIBUTION.md](docs/PLUGIN_DISTRIBUTION.md) | MCP registry and agent-plugin distribution order |\n| [OPENCLAW.md](docs/OPENCLAW.md) | OpenClaw integration |\n| [NEMOCLAW.md](docs/NEMOCLAW.md) | NemoClaw integration |\n| [KERNEL.md](docs/KERNEL.md) | Protocol kernel spec |\n| [CONFIDENTIAL.md](docs/CONFIDENTIAL.md) | Confidential execution |\n| [NOSTR.md](docs/NOSTR.md) | Nostr publication adapter |\n| [STORAGE_PROFILE.md](docs/STORAGE_PROFILE.md) | Storage profiles |\n| [GCP_SINGLE_VM.md](docs/GCP_SINGLE_VM.md) | Single-VM self-host deployment wrapper |\n| [MARKETPLACE.md](docs/MARKETPLACE.md) | Marketplace integration and the default public marketplace |\n| [RELAY.md](docs/RELAY.md) | Relay ingress v1 contract (outbound tunnel, zero-DNS public HTTPS) |\n| [ARBITER.md](docs/ARBITER.md) | MVP complaint and marketplace enforcement boundary |\n| [HOSTED_TRIAL.md](docs/HOSTED_TRIAL.md) | Public contract for the hosted trial |\n| [RELEASE.md](docs/RELEASE.md) | Release process |\n| [NAME_COHERENCE.md](docs/NAME_COHERENCE.md) | Lightweight launch name and registry-risk note |\n| [PAYMENT_MATRIX.md](docs/PAYMENT_MATRIX.md) | Supported payment rails and verification coverage |\n| [CONFIGURATION.md](docs/CONFIGURATION.md) | Environment-variable configuration reference |\n| [MANIFEST.md](docs/MANIFEST.md) | Service manifest format (froglet-service.toml) |\n| [PROVIDER_ONBOARDING.md](docs/PROVIDER_ONBOARDING.md) | Publish path and provider onboarding |\n| [API_ERRORS.md](docs/API_ERRORS.md) | API error reference — status codes and error shapes |\n| [THREAT_MODEL.md](docs/THREAT_MODEL.md) | Assets, trust boundaries, key-compromise runbook |\n| [DOCKER.md](docs/DOCKER.md) | Local compose and container deployment |\n| [MOUNTS.md](docs/MOUNTS.md) | Capability-gated data mounts for published services |\n| [ROLE_TOOL_ARCHITECTURE.md](docs/ROLE_TOOL_ARCHITECTURE.md) | Role and tool architecture |\n| [FEEDBACK.md](docs/FEEDBACK.md) | MVP feedback channel and first-four-weeks triage loop |\n| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Community standards (Contributor Covenant 2.1) |\n| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute |\n\nFirst-party hosted deployment tooling and operator runbooks are maintained\nseparately from the public protocol and self-host docs in this repo.\n\n---\n\n\n\n**[Docs Manual Source](docs-site/src/content/docs/docs.mdx)** · **[Releases](https://github.com/armanas/froglet/releases)** · **[Discussions](https://github.com/armanas/froglet/discussions)** · **[Issues](https://github.com/armanas/froglet/issues)** · **[License](LICENSE)**\n\n
\n",
"bytes": 20493,
"sha": "e609181202037cf998762bd723664ab8eb0b9a1d1fb86beb6b421ced939f78ca",
"repo_slug": "armanas/froglet",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_armanas_froglet_845bb5bb/readme"
}