1
Search first
Use settlemesh search or /v1/services/search to find the current service instead of guessing provider names.
Loading SettleMesh…
Preparing this page without starting an action.
Loading SettleMesh…
Preparing this page without starting an action.
Agent Operating Guide
Agents should not memorize provider endpoints. They should install the CLI, search the service catalog and inspect schemas first, then log in only when the selected operation requires an account.
Read https://www.settlemesh.io/agent.md first.
Use SettleMesh by searching services before invoking tools.
When using terminal commands, prefer --json, quote before a costly call, and log in only when that action requires it.settlemesh help --json
settlemesh search "what the user wants" --json
settlemesh show <service-or-operation-id> --json
settlemesh login # only when the next action requires an account
settlemesh quote <entrypoint-id> --input '{...}' --json
settlemesh call <entrypoint-id> --input '{...}' --wait --json1
Use settlemesh search or /v1/services/search to find the current service instead of guessing provider names.
2
Use settlemesh show before invoking an unfamiliar service or operation. The contract reveals availability, inputs, and next steps.
3
Use settlemesh quote before a paid action, --json, and --wait for async jobs. A direct user request already authorizes an ordinary deploy, publish, or paid call; ask separately only before destructive, high-impact, authorization-expanding, or truly irreversible effects.
Deploy apps
Build normally with any agent or editor, then inspect settlemesh deploy preflight . --full-stack --json. Deployment authorization is currently unavailable, so source deploy fails closed before upload, build, payment, or publication.
Publish agents
Use settlemesh agents create, agents deploy, and agents invoke. A public hosted agent appears in search when it is active and has a ready version; there is no default reviewer queue.
Share local compute
Use settlemesh worker start to expose local model or compute endpoints, then others can discover and invoke the offer.
Deploy an app
The browser dashboard is read-only for app delivery: it does not upload source or change production traffic. The intended source-deploy entrypoint remains the owner CLI, but the current release authorization gate returns deployment_authorization_unavailable and fails closed before upload, build, payment, or publication. Passing preflight does not override that gate or produce a candidate, preview, or live URL.
The target policy remains automatic publication after mechanical checks pass, with no default human approval queue. That is the intended product behavior after release authorization becomes available, not a claim that deployment succeeds today.
# Read runtime and admission before any source is uploaded.
settlemesh deploy preflight . --full-stack --json
# Intended owner CLI entrypoint. Current release authorization stops this with
# deployment_authorization_unavailable before upload/build/payment/publication.
settlemesh deploy . --name my-app --full-stack --wait --json{
"runtime": "<string: no-upload runtime estimate>",
"admission": {
"can_start_now": "<boolean: current snapshot admissible?>",
"code": "<string?: repair code when not admissible>",
"message": "<string?: repair guidance when not admissible>"
},
"quota": "...",
"app_slot_fee": "...",
"balance": "..."
}settlemesh deploy preflight . --full-stack --json is an authenticated, read-only snapshot of your current app slots, the exact new-app slot overage (if any), and whether your Aev balance covers it. It uploads no source and creates no hold, app, or reservation. Interpret the JSON before upload:runtime is a no-upload estimate; admission.can_start_now true means the current snapshot is admissible, while false means repair using the returned admission.code and admission.message. Either result is rechecked at build time and creates no reservation, hold, app, or source upload—preflight is not a guarantee that a later deploy will start. Current release authorization remains unavailable even when this snapshot sayscan_start_now. This quote intentionally covers the new-app slot only, not separately metered build or runtime usage. Use settlemesh apps list --json to inspect existing apps and settlemesh aev balance --json for your general balance.
Existing app records
For an app or build id that already exists, read status and logs before any CLI retry. candidate_ready and preview are non-serving states, not production traffic. Read a serving URL with deploy url; build status is not the URL. A missing URL is not a successful deployment.
# Read-only observation: no upload, deploy, publish, charge, or cleanup starts here.
settlemesh deploy status <app-id> --json
settlemesh deploy logs <build-id> --json
settlemesh deploy url <app-id> --json
# Intended retry path after release authorization becomes available.
settlemesh deploy . --app-id <app-id> --full-stack --wait --jsonA normal deploy or retry does not need an additional confirmation: the direct owner request is its intent. It still cannot bypass unavailable release authorization. A preview record is non-serving; neither it nor a failed gate is a manual-review queue.
Destructive cleanup is different. Use it only after separate confirmation for the named app. It takes the app offline immediately and starts only a best-effort provider cleanup attempt. A successful response does not prove every provider resource is absent; the browser never performs it.
settlemesh apps delete <app-id> --confirmPublish a service
A public dynamic service becomes searchable automatically once its publish admission and mechanical gates pass: runnable examples, pricing floor, allowed hosts, and abuse controls. Manual review is an operator-controlled exception, not the normal owner journey. Hosted agents, worker offers, and app APIs likewise publish from their owner-controlled CLI paths once their own readiness checks pass.
settlemesh services upload ./service.yaml --json
settlemesh services config-status <service-id> --json
# Read publish_fee.fee_required separately from publish_fee.will_charge.
# Show publish_fee.publish_fee_credits when a fee is required.
# Continue only when publish_fee.admission.can_start_now is true.
# Otherwise follow admission.code, admission.message, and admission.fix; do not publish.
settlemesh services publish <service-id> --visibility public --json
settlemesh search <service-id>The authenticated GET /v1/dynamic-services/<service-id>, GET /v1/dynamic-services/<service-id>/config-status, and POST /v1/dynamic-services/<service-id>/validate surfaces expose the same top-level publish_fee authority. Calling these inspection and validation surfaces creates no hold, charge, or publication.
Do not infer a fee from a manifest, quota, or will_charge alone. fee_required is separate from will_charge. Branch on admission.can_start_now; when false, follow admission.code, admission.message, and admission.fix instead of sending publish. With a positive free quota, recovery starts with inspection only: list existing services without changing them. The server reports the exact count, such as freeing 1 shared service entry. Making an existing shared service private is a high-impact discoverability and caller change; the request to publish a new service does not authorize it.confirmation_requiredmeans stop and obtain a separate explicit request naming each affected service. Only then use the explicitly-authorized command template and read the target's config-status again. This boundary applies to changing existing services; the ordinary publish itself still needs no duplicate confirmation. With a zero free quota, shared publish is currently UNABLE and keeps this service private; after atomic publish settlement admission is enabled, run the returned target config-status readback before publishing. A rejected first-time site publish says no site record was created, never sends you to dynamic-service config-status, and returns the site-specific publish command to retry.
# Positive free quota — inspection only until separately authorized:
settlemesh services list --json
# confirmation_required: stop. The new publish request does not authorize changing existing services.
# Only after a separate explicit request names each affected service:
settlemesh services publish <explicitly-authorized-existing-service-id> --visibility private --json
settlemesh services config-status <service-id> --json
# Zero free quota: shared publish is currently UNABLE and keeps this service private.
# After atomic publish settlement admission is enabled, read the target again:
settlemesh services config-status <service-id> --jsonFor publish_settlement_unavailable, if the earlier mechanical gates pass and the admission state is unchanged, publish returns 503 with the same recovery fields before any hold, capture, or publication. Free or fee-disabled mechanical publish remains automatic after its gates pass, with no default review queue and no duplicate confirmation.
Put that URL in Cursor, Codex, Claude Code, CI, or hosted agent instructions. It is intentionally short, stable, and focused on how to discover and call SettleMesh safely.