Publish A Froglet Service

Agent-grade publish

One authoring contract. Two deliberate calls for anything public.

The first call builds the exact package and returns a non-mutating consent summary. The second rebuilds once and proceeds only when the user approves that exact hash. CLI and native MCP use the same Rust engine.

The safe default

Installation and publication are separate approvals:

1. Bootstrap verifies and installs the exact Release Bundle, starts the local node, configures the native MCP bridge, and proves free local execution.
2. marketplace_publish builds the service without publishing it and returns status: "approval_required" plus a consent_hash.
3. The agent shows the user the package/build digests, schemas, capabilities, limits, provider identity, exact endpoint, relay trust boundary, price, settlement rail, and commerce responsibility.
4. Only after approval does the agent repeat the same call with the exact consent_hash.

The approved call rebuilds the package once. If source, data, dependency lock, schema, capabilities, price, provider identity, or endpoint changed, the hash changes and publication stops before the provider-control mutation.

Native MCP call shape

Author a directory containing froglet-service.toml and the referenced source or data file. Then call the single froglet tool:

{
  "action": "marketplace_publish",
  "project_dir": "/absolute/path/to/my-service",
  "host": "relay"
}

The first response is a plan, not a published service:

{
  "status": "approval_required",
  "consent_hash": "<64 lowercase hex characters>",
  "summary": {
    "service_id": "my-service",
    "hosting": "relay",
    "provider_id": "<provider identity>",
    "public_url": "https://<identity-assigned-host>",
    "package_digest": "<exact package digest>",
    "publish_request_digest": "<exact canonical request digest>",
    "settlement_method": "none"
  }
}

After the user approves that exact summary:

{
  "action": "marketplace_publish",
  "project_dir": "/absolute/path/to/my-service",
  "host": "relay",
  "consent_hash": "<the exact approved hash>"
}

Do not infer approval from the original prompt, retry automatically with a new hash, or hide warnings. A stale approval is intentionally unusable.

The approved response contains requester-canary and marketplace offer evidence only when the external marketplace activates the exact candidate. Tor, self-hosted, paid, or policy-held candidates can truthfully return pending_review with no active offer URL or requester canary. A successful local relay composition does not prove that a first-party public relay or its DNS/TLS ingress is deployed.

Shell equivalent

From the authored service directory:

froglet-node publish --host relay --plan --json

Review the returned summary, then use its exact hash:

froglet-node publish --host relay \
  --approve-consent <exact-consent-hash> --json

For a private proof, --host local builds, verifies, and stores a local revision without opening a public transport or registering a listing.

What the approved pipeline proves

The shared publication engine executes this order:

build exact immutable package
  -> read-only provider identity/transport preflight
  -> exact consent hash
  -> user approval
  -> rebuild once and compare
  -> provider-private fixture execution
  -> signed immutable Publication Revision
  -> approved endpoint confirmation
  -> marketplace pending-validation candidate
  -> marketplace-owned exact-revision canary
  -> atomic activation and renewable health lease
  -> exact offer projection
  -> independent requester-side canary

Each claim remains separate. A local fixture does not prove reachability; reachability does not prove marketplace activation; activation does not prove an independent requester invocation; none of those proves a payment.

Hosting choices

Choice	Public	Behind NAT	Extra account/dependency	Status
local	no	yes	none	implemented
relay	yes	yes	live relay operator endpoint	implemented locally; public deployment tracked separately
tor	yes	yes	Tor sidecar + marketplace Tor egress	implemented
self	yes	depends	user-operated HTTPS origin	implemented
managed	yes	yes	selected operator adapter	neutral manifest/operator contract implemented; publish-engine orchestration not yet wired

Relay is the intended dependency-minimal public path. The node dials outbound WSS and receives an identity-derived HTTPS origin; the user needs no inbound port, certificate, or DNS account. The relay terminates TLS, can observe plaintext, and applies operator quotas, so those facts are part of consent. Bootstrap plans the official relay URL and suffix dormant by default: that derives an endpoint but opens no WSS without an exact durable grant. A public publication plan fails before approval unless the configured relay is actually up and has returned the exact identity-derived HTTPS origin. That preflight proves this configured node-to-relay session, not general Internet reachability or a first-party deployment.

froglet-service/v4 uses a neutral managed target/profile. AWS Lightsail is a compatibility adapter in froglet-services, not a manifest variant or product architecture. The legacy v3 hosting.fly input is readable only for migration; new authoring must not invoke flyctl implicitly.

Data and function authoring

The native builder supports:

• read-only JSON, explicitly typed CSV, and SQLite data services;
• embedded WAT/Wasm without an external compiler;
• resolver-free locked Python bundles made from exact pure-Python wheels; and
• digest-pinned OCI execution through a separate authenticated rootless worker.

The clean-host bootstrap itself publishes and invokes a user-supplied JSON fixture, so installation proves a useful data service rather than only a health endpoint. Arbitrary OCI is an advanced capability, not a prerequisite for the first service.

Settlement

Free (none) is the default and needs no payment account. A paid publication must explicitly select lightning or stripe, and consent binds the amounts, currency, rail, direct-provider payee responsibility, platform fee, external fee uncertainty, and refund boundary. The marketplace does not silently become merchant of record or payout intermediary.

Stripe production publication expects a caller/platform-issued Shared Payment Token. Froglet’s token-mint helper is test-only and refuses live keys. Do not claim live money movement from unit tests or test-mode PaymentIntents.

Lifecycle after publication

The same native tool exposes bounded operations over immutable revisions:

• publication_status
• publication_logs
• publication_pause
• publication_resume
• publication_rollback with an exact revision hash
• publication_unpublish with confirm_service_id exactly matching the target

Pause and unpublish remove the active projection without deleting signed history. Rollback activates only an already validated immutable revision.

Current proof boundary

The implementation evidence matrix distinguishes local code/tests from live infrastructure. In particular, local relay composition can prove the real WebSocket tunnel, registration, canaries, projection, invocation, disconnect, and lease expiry while still not proving public DNS, trusted TLS, Internet ingress, a clean external host, or a live payment. Consult the matrix before telling a user a first-party public path is online.

Full reference

• docs/AGENT_FIRST_PUBLICATION_PLAN.md
• docs/PUBLICATION_CONTRACT.md
• docs/MANIFEST.md
• docs/RELAY.md
• froglet-publish-engine/