---
title: Quickstart
description: "Run Froglet locally through an agent without cloning the repo first."
---

<div class="learn-hero compact">
  <div>
    <div class="learn-pill">Agent-first install</div>
    <p class="learn-lead">Start a local Froglet node without a repo clone, a domain, or a payment account.</p>
    <p class="learn-sublead">The normal path is one tiny bootstrap, then everything else goes through <code>froglet-mcp</code>. The first proof is a free local <code>demo.add</code> service. Payments, public registration, Tor, and backend integrations are explicit follow-up decisions.</p>
    <div class="learn-chip-row">
      <span class="learn-chip">No git clone</span>
      <span class="learn-chip">No paid domain</span>
      <span class="learn-chip">MCP is the control surface</span>
    </div>
  </div>
</div>

## TL;DR

```bash
curl -fsSL https://froglet.dev/agent | bash
```

The bootstrap:

- installs the signed `froglet-node` binary
- writes `~/.froglet/agent/compose.yaml`
- starts provider/runtime from published GHCR images matching the latest release
- writes MCP config for the selected agent target
- prints JSON with `provider_url`, `runtime_url`, MCP config path, and the next recommended MCP actions

It does **not** publish public services, register with the marketplace, or turn
on paid rails. Those steps happen later through `froglet-mcp` after local health
checks pass.

## Prerequisites

- Linux x86_64 / arm64 or macOS arm64
- `curl`
- Docker with Compose v2 for the default provider/runtime stack
- Optional: Tor for zero-cost public registration from behind NAT
- Optional: a public VM IP if you want a Froglet-managed clearnet subdomain

You do not need Git, Rust, Node.js, Cloudflare, or a paid domain for the default
bootstrap path.

## Agent Targets

Default target:

```bash
curl -fsSL https://froglet.dev/agent | bash
```

Codex target:

```bash
FROGLET_AGENT_TARGET=codex curl -fsSL https://froglet.dev/agent | bash
```

Manual target:

```bash
FROGLET_AGENT_TARGET=manual curl -fsSL https://froglet.dev/agent | bash
```

OpenClaw still needs the repo-local OpenClaw plugin folder. Use the MCP path
above for no-clone setup; use source mode only if you are developing or testing
the OpenClaw plugin itself.

## First MCP Calls

After the bootstrap finishes, restart or point your agent at the printed MCP
config path. Then have the agent call the Froglet MCP tool in this order:

1. `status`
2. `publish_artifact` with `template: "demo.add"`
3. `list_local_services`
4. `invoke_service` for `demo.add.local` with `{"a":7,"b":5}`

Expected first proof: the local service returns `{"sum":12}` and the agent can
report provider/runtime health, service metadata, and receipt evidence.

If you already have a local provider/runtime and only need the MCP stdio server,
use the published package directly:

```bash
npx froglet-mcp
```

If you only want the hosted no-install proof, do not start a local node. Use
`https://froglet.dev/llms.txt`.

## Payment Decisions

The bootstrap starts with `payment_rail=none`. That is the normal user path.
Ordinary buyers should not configure LND, channel liquidity, Stripe API keys, or
x402 wallets to try Froglet. Paid rails are explicit operator choices:

| Rail | When to choose it | Human checkpoint |
|------|-------------------|------------------|
| `none` | First local demo and free services | none |
| `lightning-lnd-rest` | Operator-controlled Bitcoin Lightning settlement. Reference rail, proven on regtest; mainnet pending channel liquidity | LND REST URL, macaroon, TLS cert, backups, funded channel liquidity |
| `stripe-test` | Card-flow development on Stripe's agentic Shared Payment Token model (US-only; froglet↔froglet is test-only) | Stripe test secret key and webhook secret |
| `stripe-live` | Production Stripe via the agentic SPT model — buyers are external ACP agents, not froglet nodes (US-only) | fresh explicit approval, live secret, tiny live payment/refund proof |
| `x402` | Daemon-only USDC-style rail for self-hosted compute endpoints. **Not** a marketplace publish-path option | wallet address, facilitator, verify/settle proof |

If an agent calls `plan_install` or `get_install_guide` without a rail, MCP
returns `decision_required`. Pick `none` for the first demo and for normal
customer evaluation. Do not enter real payment secrets until the local free path
is healthy and the operator has deliberately chosen a paid rail. Published
marketplace services settle with `none`, `lightning`, or `stripe`; x402 stays at
the daemon level. No real money has moved yet anywhere (test-mode / regtest
only).

:::caution[Buying side: set a spend budget before giving an agent a wallet]
A node that *pays* for services refuses paid deals — fail-closed — until you
set `FROGLET_REQUESTER_SPEND_BUDGET_MSAT` (cumulative budget, persistently
tracked; optional per-deal cap via `FROGLET_REQUESTER_MAX_DEAL_MSAT`).
Enforcement happens before any money moves on every rail; check the ledger
with `GET /v1/runtime/spend`. Free deals need no budget. See
[Configuration](https://github.com/armanas/froglet/blob/main/docs/CONFIGURATION.md).
:::

## Public Registration Choices

Marketplace registration requires the provider to advertise the exact public
URL that the marketplace will fetch. There are three practical paths:

| Path | Cost | Works behind NAT | Marketplace URL |
|------|------|------------------|-----------------|
| Local only | $0 | yes | not registered |
| Tor | $0 | yes | `http://<onion>.onion` |
| Froglet-managed subdomain | $0 | no, needs public inbound IP | `https://<slug>.providers.froglet.dev` |

Raw IPs and self-signed clearnet URLs are not accepted by the public
marketplace. They create poor trust and UX for requesters.

### Tor Registration

Use Tor when the user has no domain and no public inbound internet. After local
health passes, ask MCP to plan a Tor exposure. The registration call is:

```json
{
  "action": "marketplace_register",
  "registration_transport": "tor"
}
```

The provider must advertise the same onion URL in `/v1/node/capabilities`, and
the marketplace/indexer runtime must have Tor SOCKS access.

### Froglet-Managed Subdomain

Use this when the provider is on a VM or home network with public inbound
connectivity but the user does not want to buy a domain.

1. Agent reads the local provider identity from `status`.
2. Agent calls `marketplace_domain_claim` with `provider_id`, optional
   `requested_slug`, and the public IP.
3. Agent calls `marketplace_domain_complete` with the returned claim.
4. Operator DNS automation creates a DNS-only record under
   `providers.froglet.dev`, or the claim returns `pending_operator_dns`.
5. Agent configures HTTPS for the hostname and then calls
   `marketplace_register`.

This is not a proxy. The provider still hosts its own Froglet node.

## Backend Integration Flow

After the free demo works, the agent should ask what the user wants to expose:

- demo service
- local script
- HTTP backend
- mounted files
- database-backed helper
- OCI image
- GPU service

The agent should generate the smallest working config, publish one service,
invoke it locally, then decide whether public exposure and marketplace
registration are needed. OCI and GPU are advanced paths, not the first happy
path.

## Source / Contributor Mode

Clone the repo only when you are developing Froglet itself, testing the
OpenClaw plugin, or changing the checked-in Compose setup:

```bash
git clone https://github.com/armanas/froglet.git
cd froglet
```

Repo-local helpers remain available:

```bash
./scripts/setup-agent.sh --target claude-code
./scripts/setup-agent.sh --target codex
docker compose up --build -d
```

That is contributor mode, not the normal user path. Payment helpers are
operator-only and should be run separately after the free path is healthy.

## Fresh-Host Proof

The disposable-host proof exercises the no-clone bootstrap in an isolated
`HOME`:

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

For setup-only evidence without starting Docker:

```bash
curl -fsSL https://raw.githubusercontent.com/armanas/froglet/main/scripts/fresh_host_quickstart_smoke.sh | bash -s -- --skip-start
```

## Related

- [Connect Agents](/learn/agents/)
- [Payment Rails](/learn/payment-rails/)
- [Marketplace](/marketplace/overview/)