Connect Agents

Agent setup

Connect agents to a real local or self-hosted Froglet node.

The verified installer connects Codex or Claude Code through Froglet’s native MCP bridge. Start with the sharing walkthrough. The optional npm server provides broader compatibility actions; the hosted trial is not a setup prerequisite.

No-Clone Agent Bootstrap

For a user who wants a local Froglet node, use the copyable immutable-release resolver in Quickstart. It verifies the uploaded agent-bootstrap.sh digest before running its non-mutating plan. Present that plan and wait before running the returned exact execute command.

The plan binds the immutable Release Bundle, exact platform froglet-node asset, bootstrap/install/configuration script bytes, filesystem impact, and service-manager changes before any persistent write. Execution recomputes and requires the exact approval hash. It then verifies the exact froglet-node asset checksum, starts one dual-role native service through launchd or user systemd, writes an MCP config that runs froglet-node mcp, and exits only after a non-seeding MCP status proof plus transient read-only data publication/invocation/confirmed-unpublish evidence. No Node.js, npm, Python, Docker, or jq is required on this default lane. A digest-pinned image is the fallback only when native service management is unavailable.

Branch on the bootstrap’s install_mode. Native mode emits the focused actions documented below. Docker fallback configures the image-backed compatibility bridge and emits its own next_mcp_actions; do not assume native publication lifecycle actions are present there.

Use Codex instead of Claude Code:

FROGLET_AGENT_TARGET=codex sh "$bootstrap" plan
FROGLET_AGENT_TARGET=codex sh "$bootstrap" execute '<install_approval_hash>'

OpenClaw no-clone setup is not the default today because OpenClaw still loads a repo-local plugin folder. Use the MCP path above for normal users and source mode only for OpenClaw plugin development.

Native MCP installed by bootstrap

The generated Claude Code or Codex config runs the installed binary directly:

froglet-node mcp

The native bridge’s current source supports status, invoke_service, run_compute, read-only get_task, two-step marketplace_publish, and exact publication status/logs/pause/resume/rollback/ confirmed-unpublish. For public publication, the first call is non-mutating and the second must carry the exact user-approved consent_hash.

The available actions depend on the exact binary. Compute and task recovery are implemented in the current source; do not assume that every installed release contains them. Inspect the MCP tool listing for that installation. The repeatable local demo builds the current checkout rather than substituting an older installed binary.

local_proof invokes the bundled demo only when an operator deliberately enables that catalog. Clean installation does not seed it.

Submit one bounded Wasm program

Native run_compute accepts complete Wasm v1 bytes as wasm_module_hex or a local compiled file through native-only wasm_module_path, and an explicit JSON input (null is allowed), using the froglet.wasm.run_json.v1 ABI. It does not accept Python/source text, OCI packages, mounts or host capabilities. The file path must be absolute and refer to a regular nonsymlink file; supply exactly one module argument. The program is limited to 256 KiB and the canonical JSON input to 128 KiB; execution limits come from the provider’s signed Quote.

An actual Codex session has exercised retrieval, native file-based computation and result recovery on one development Mac. That evidence does not establish clean OS installation, first-time-user usability or every agent host.

Supply an explicit, non-whitespace idempotency_key of 1–128 UTF-8 bytes. Keep the exact key, program, input and provider when reconciling an uncertain submission. Use a new key for new work. Reconciliation is not a guarantee that an ambiguous submission was recovered; if no durable admission can be found, inspect the reported uncertainty before resubmitting.

timeout_secs is the polling window, from 0 to 60 seconds (default 15), not the program’s execution limit. A pending response retains its deal_id and retry key. Call get_task with task_id set to that returned deal_id to read the existing operation without resubmitting work or making a new payment. Never replace the key merely because polling timed out.

Calls are free-only when max_price_sats is omitted or 0. Paid Lightning computation uses the configured wallet and the node’s cumulative spending budget; an explicit per-call ceiling cannot override that budget. The native action has no caller-supplied Stripe token argument. Advanced Stripe callers use the requester runtime API; its optional automatic minting helper is sandbox-only. The local demo configures no wallet or paid backend. A successful receipt check binds the result and signed transaction evidence; it does not establish scientific correctness or usefulness.

MCP supplies the agent tool interface. Optional A2A supplies configured remote task transport around the same runtime and signed deal. See Agent Interoperability for the supported profile, setup and recovery limits.

Broader compatibility MCP from npm

Use the published JavaScript MCP package when an existing local or self-hosted node needs broader discovery, settlement, installation-planning, or legacy integration actions:

npx froglet-mcp

That command starts an MCP stdio server. It defaults to FROGLET_PROFILE=local, FROGLET_PROVIDER_URL=http://127.0.0.1:8080, and FROGLET_RUNTIME_URL=http://127.0.0.1:8081. In that profile the agent should call:

• status first, to verify provider/runtime reachability and report missing token files or local services plainly
• plan_install if the local node is missing and the target agent, footprint, role, payment rail, network, marketplace, or first use case is still ambiguous. Prefer footprint auto for the native-first no-clone path; use native to require the user service and docker only when explicitly selected. If it returns decision_required, ask the user to pick a payment rail and recommend none for the first local proof. When complete, present its immutable release, manifest/bootstrap hashes, persistent paths, process-manager impact, exact command preview, and approval hash
• get_install_guide only after explicit approval, with the exact returned release_tag and install_approval_hash plus the unchanged profile
• plan_use_case after local health is verified and before implementing the user’s first consumer, provider, evidence, payments, batch, or GPU workflow
• service, settlement, marketplace, and publication actions only after the local node is reachable

The older hosted trial at try.froglet.dev is retired; do not call it. The root https://froglet.dev/llms.txt routes agents to the appropriate workflow. Paid rails, persistent identity, custom service publication, long-running jobs, batch, and GPU workloads are local/self-hosted concerns.

If you are packaging Froglet into an agent host rather than adding one MCP server manually, use Plugin Distribution for the MCP Registry, Codex, Claude Code, OpenClaw, and NemoClaw order.

For MCP client config, use the package as the stdio command:

{
  "mcpServers": {
    "froglet": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "froglet-mcp"],
      "env": {
        "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": "data/runtime/froglet-control.token",
        "FROGLET_RUNTIME_AUTH_TOKEN_PATH": "data/runtime/auth.token"
      }
    }
  }
}

For Codex-style TOML:

[mcp_servers.froglet]
command = "npx"
args = ["-y", "froglet-mcp"]
[mcp_servers.froglet.env]
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 = "data/runtime/froglet-control.token"
FROGLET_RUNTIME_AUTH_TOKEN_PATH = "data/runtime/auth.token"

Local config from the repo

These helper commands are repo-local and are kept for contributors. The normal user path is /agent, not a clone. Clone only when you are developing Froglet, testing the OpenClaw plugin, or editing checked-in examples:

git clone https://github.com/AlitheaBio/froglet.git

Generate a config

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

Optional override:

cd froglet && ./scripts/setup-agent.sh --target codex --out /tmp/froglet-codex.toml

Default outputs

Target	Default output	What it configures
claude-code	.mcp.json	Project-local MCP server for Claude Code
codex	.codex/config.toml	Project-local MCP server for Codex
openclaw	.froglet/openclaw.config.json	OpenClaw plugin config with the checked-in Froglet plugin

Default values

The helper writes local-profile values unless you override them with environment variables:

• 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=<repo-root>/data/runtime/froglet-control.token
• FROGLET_RUNTIME_AUTH_TOKEN_PATH=<repo-root>/data/runtime/auth.token

When you run the local stack with Docker Compose, start it with FROGLET_HOST_READABLE_CONTROL_TOKEN=true so the provider token path above is actually readable from the host. The direct froglet-node path does not need that opt-in.

Activation

• Claude Code: restart Claude Code in the repo so it reloads .mcp.json.
• Codex: start Codex from the repo so it picks up .codex/config.toml.
• OpenClaw: use the generated config file directly and verify it with:

node integrations/openclaw/froglet/scripts/doctor.mjs \
  --config .froglet/openclaw.config.json \
  --target openclaw

Checked-in MCP examples

The repo also ships checked-in MCP examples for:

• Claude Desktop
• Cursor
• Codex
• Docker-backed MCP

Those live under integrations/mcp/froglet/examples/ and are covered by test.

Local npm profile

If you prefer the published package but already have a local Froglet node, point the MCP server at local provider/runtime URLs and token files:

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

Marketplace publication and registration

On the native lane, use two-step marketplace_publish; it performs exact registration only after provider-local verification and user approval. On the broader JavaScript compatibility lane, use wrappers instead of ad hoc HTTP:

• marketplace_register for public HTTPS or Tor registration
• marketplace_domain_claim and marketplace_domain_complete for *.providers.froglet.dev

Tor registration is allowed only through registration_transport=tor and a provider-advertised http://<v3>.onion origin. General provider_url overrides still reject onion URLs so an LLM cannot silently route normal invocations through arbitrary Tor endpoints.

Next step

After the agent config exists, try the free local compute workflow in Agent Interoperability. Use Payment Rails when you deliberately choose paid work.