Connect Agents

Agent setup

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

The no-clone install configures the native MCP bridge in the checksum-verified Froglet binary. Use llms.txt for the no-install hosted proof; use the npm server only when you need its broader compatibility actions.

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

Its focused clean-install tool supports status, invoke_service, 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.

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

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 hosted proof is intentionally separate. It lives at https://froglet.dev/llms.txt and covers only public free demo.* services. 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/armanas/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, move to Payment Rails.