Remove a host from the scheduler

Requires the master token. An API-key principal gets 403.

The host must have no environments assigned; cordon it and wait for (or destroy) its VMs first. A host that still has VMs assigned returns 409 conflict with the message host <id> still has vm <id> assigned. The named VM is one of the assigned set rather than a count, and because the check walks a map it can differ between identical calls.

DELETE/v1/hosts/{hostId}

Authorization

AuthorizationBearer token · headerrequired

`Authorization: Bearer <token>` — either the static master token (`ORCH_AUTH_TOKEN`) or a revocable API key issued via /v1/api-keys (API keys require Postgres; without a database only the master token is accepted). Master-only surfaces (exec, attach, API key management) refuse API keys with 403. **Authentication can be disabled entirely.** When neither `ORCH_AUTH_TOKEN` nor an API key store (`DATABASE_URL`) is configured — the default local-development posture — the bearer middleware becomes a pass-through: every operation this document marks as secured is reachable with no credentials, requests carry no principal, and master-only surfaces therefore admit everyone. Never run that configuration on a reachable network; set `ORCH_REQUIRE_AUTH=true` to make the orchestrator refuse to start without a master token.

fuse_sessionAPI key · cookierequired

HttpOnly session cookie set by POST /login for browser callers. Consulted only when no Authorization header is present.

Path parameters

hostIdstringrequired

Host identifier assigned by the caller.

Responses

204Host removed.

404Resource does not exist. Note the distinct code `route_not_found`, returned when the URL matches no registered route at all (wrong host, port, or path prefix) rather than a known route with a missing resource.

errorobjectrequired

Show properties

codestringrequired

Stable machine-readable code. `route_not_found` (404) means the URL matches no route this server exposes — usually a wrong host, port, or path prefix — as opposed to `not_found`, where the route exists but the resource does not. `forbidden` is emitted only by CIDR-allowlist rejections; master-only refusals (exec, attach, API key management) return 403 with code `unauthorized`.

Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplemented

messagestringrequired

Human-readable description.

detailsobject

Optional stable, non-sensitive metadata (e.g. ids, counts). Omitted when empty.

409Conflicts with current state (e.g. duplicate task assignment).

errorobjectrequired

Show properties

codestringrequired

Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplemented

messagestringrequired

Human-readable description.

detailsobject

Optional stable, non-sensitive metadata (e.g. ids, counts). Omitted when empty.

500Unexpected server error.

errorobjectrequired

Show properties

codestringrequired

Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplemented

messagestringrequired

Human-readable description.

detailsobject

Optional stable, non-sensitive metadata (e.g. ids, counts). Omitted when empty.

Request

curl -X DELETE "http://localhost:8080/v1/hosts/string" \
  -H "Authorization: Bearer YOUR_TOKEN"

const response = await fetch("http://localhost:8080/v1/hosts/string", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});

import requests

response = requests.delete(
    "http://localhost:8080/v1/hosts/string",
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    },
)

Response

Host removed.