1
Search first
Use semesh search or /v1/services/search to find the current service instead of guessing provider names.
Loading Semesh…
Preparing this page without starting an action.
Loading Semesh…
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://semesh.io/agent.md first.
Use Semesh 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.semesh help --json
semesh search "what the user wants" --json
semesh show <service-or-operation-id> --json
semesh login # only when the next action requires an account
semesh quote <entrypoint-id> --input '{...}' --json
semesh call <entrypoint-id> --input '{...}' --wait --json1
Use semesh search or /v1/services/search to find the current service instead of guessing provider names.
2
Use semesh show before invoking an unfamiliar service or operation. The contract reveals availability, inputs, and next steps.
3
Use semesh 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 semesh deploy preflight . --full-stack --json. Deploy only when the live, runtime-specific admission.can_start_now result is true; a false result stops before upload, build, payment, or publication.
Publish agents
Use semesh 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 semesh 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 source-deploy entrypoint is the owner CLI. Run its authenticated preflight immediately before each logical deploy: a false admission.can_start_now result fails closed before upload, build, payment, or publication; a true result authorizes using the same source and stack intent immediately, but only deployment status and URL readback prove the final serving state.
Publication is automatic after mechanical checks pass, with no default human approval queue. A passing snapshot is not a reservation or a guarantee against a later provider failure.
# Read tool availability, runtime, and admission before any source is uploaded.
semesh tool show app_deployments.create --json
semesh deploy preflight . --full-stack --json
# Continue only when admission.can_start_now is true, using the same source and stack intent.
semesh 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>",
"fix": "<string?: exact recovery action when not admissible>"
},
"quota": "...",
"app_slot_fee": "...",
"balance": "..."
}semesh 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, admission.message, and admission.fix. Either result is rechecked at build time and creates no reservation, hold, app, or source upload—preflight is not a guarantee that a later provider effect will succeed. When the snapshot says can_start_now, run the matching deploy immediately. This quote intentionally covers the new-app slot only, not separately metered build or runtime usage. Use semesh apps list --json to inspect existing apps and semesh aev balance --json for your general balance.
Current MVP serving rails are Next.js through OpenNext for full-stack apps and plain static output for HTML/CSS/JS or a prebuilt SPA. Container and Dockerfile sources are recognized for future extension, but their preflight returns deployment_runtime_lifecycle_unavailable before upload or provider effects. Use a supported rail instead of claiming a container or Cloud Run deployment.
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.
semesh deploy status <app-id> --json
semesh deploy logs <build-id> --json
semesh deploy url <app-id> --json
# Retry only after a fresh preflight passes for the same source and stack intent.
semesh 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 a false live admission result. 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.
semesh 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.
semesh services upload ./service.yaml --json
semesh 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.
semesh services publish <service-id> --visibility public --json
semesh 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:
semesh 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:
semesh services publish <explicitly-authorized-existing-service-id> --visibility private --json
semesh 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:
semesh 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 Semesh safely.