Deploy a template
Installs a template on a running server without logging in to it, and returns an operation to track it.
Access: API key: vm:write · Session: developer, admin or owner.
confirm_portsmust list every port the template (and any template it needs) opens, as443/tcpor443; otherwise400 ports_not_confirmed. Only ports that were not already open are added, and removal closes only those.- Templates it needs (
requires) that the server does not have are deployed first, in the same request, and returned independencies. inputsare checked against the template's input types; unknown names are refused. Inputs reach the server as data, never as commands.- The server must run a supported system with enough memory and disk (
409 incompatible_server). One deployment of a template per server; ports already used by another deployment and a change already running on the server return409. - A run whose result cannot be confirmed leaves the deployment
unknown: run a health check, then retry with update. Paused templates return503 templates_paused.
AuthorizationBearer <token>Send Authorization: Bearer <token>. A token is an API key (lb_live_…, scoped, for programs) or a session (lb_sess_…, from signup or login, for people). See Authentication above.
X-Org-ID?stringSessions only: act on this organization (you must be a member). Default: your first organization.
application/json- body
vm_id*stringtemplate*stringinputs?Values for the template's inputs.
confirm_ports?array<string>Ports you agree to open to the internet.
script?stringYour edited install script (at most 24 KB). Editing scripts may not be available yet (403); a script identical to the template's is always accepted. Only a signed-in workspace owner or admin, or the person who bought the server, may send one, and never for an imported server (403). The deployment is marked customized and not updated by Layerbeat.
Accepted: the template is being deployed
application/json- response
deployment*dependencies*array<>Templates deployed first in the same request.
operation*curl -X POST 'https://layerbeat.com/v1/deployments' \ -H 'Content-Type: application/json' \ -d '{ "vm_id": "vm_gnkrp6zuxvsqki7sqxeluvsw2y", "template": "supabase", "inputs": { "domain": "supabase.example.com", "email": "ops@example.com" }, "confirm_ports": [ "80/tcp", "443/tcp" ]}'{ "deployment": { "id": "dep_7m2k9q4w8x3z5t6v1b0n2h4ra", "template": { "id": "supabase", "name": "Supabase", "kind": "service" }, "version": "1.0.0", "latest_version": "1.0.0", "update_available": false, "customized": false, "status": "deploying", "server": { "id": "vm_gnkrp6zuxvsqki7sqxeluvsw2y", "name": "agent-01" }, "url": null, "note": null, "error": null, "output": null, "ports_opened": [], "operation": { "id": "op_4yw4xmradad4bstgr4d5qtreb4", "type": "template.deploy", "status": "pending" }, "created_at": "2026-10-10T10:00:00Z", "updated_at": "2026-10-10T10:04:00Z", "checked_at": null }, "dependencies": [ { "id": "dep_2c8v5n1m7k3x9z4q6w0t8r2ya", "template": { "id": "docker", "name": "Docker", "kind": "service" }, "version": "1.0.0", "latest_version": "1.0.0", "update_available": false, "customized": false, "status": "deploying", "server": { "id": "vm_gnkrp6zuxvsqki7sqxeluvsw2y", "name": "agent-01" }, "url": null, "note": null, "error": null, "output": null, "ports_opened": [], "operation": { "id": "op_9b3c7d1e5f2a8g4h6j0k2m4nq", "type": "template.deploy", "status": "pending" }, "created_at": "2026-10-10T10:00:00Z", "updated_at": "2026-10-10T10:04:00Z", "checked_at": null } ], "operation": { "id": "op_4yw4xmradad4bstgr4d5qtreb4", "type": "template.deploy", "status": "pending", "vm_id": "vm_gnkrp6zuxvsqki7sqxeluvsw2y", "volume_id": null, "deployment_id": "dep_7m2k9q4w8x3z5t6v1b0n2h4ra", "steps": [ { "name": "waiting_for_dependencies", "status": "running" }, { "name": "opening_ports", "status": "pending" }, { "name": "running", "status": "pending" } ], "result": null, "error": null, "created_at": "2026-10-10T10:00:00Z", "finished_at": null }}