Skip to content
Fuse
Esc
↑↓navigate↵open⌘Jpreview

Create environment

Creates a VM, uploads the manifest, starts the agent, and assigns the task. Blocks until the VM is running or creation fails. The manifest and secrets are passed inline as byte strings; a future revision may add manifest-ref indirection.

GPU requests are validated at the API boundary (not just in the CLI): negative gpus, a malformed gpu_profile, a profile with gpus < 1, or a profile on a non-MIG gpu_kind each return 400 on the first failure. gpu_profile is lowercased on the way in. A GPU request with no registered GPU host fails 503 (gpu workloads require a registered gpu host). manifest_inline must be standard base64; a bad encoding is a 400. Secrets are validated against the manifest before provisioning, and secret values are redacted from error messages.

Placement is validated at the boundary too: a malformed spec.labels key or value is a 400, and an unknown spec.host_id is a 404 before any VM is created. A pin to a real but ineligible host, and a label selector that matches no host, both fail 503 with a message naming the gate that rejected them.

POST/v1/environments
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.
or
fuse_sessionAPI key · cookierequired
HttpOnly session cookie set by POST /login for browser callers. Consulted only when no Authorization header is present.
Request body
requiredapplication/json
task_idstringrequired
Caller-assigned task identifier. Must be unique.
specobjectrequired
Hardware requirements. Nominally required, but the server does not currently reject a missing/zero spec; scheduling against registered hosts is what fails a zero-resource request.
Show properties
cpusinteger<int32>
min 0
ram_mbinteger<int32>
min 0
storage_gbinteger<int32>
min 0
gpusinteger<int32>
Count of GPU devices requested. Zero means no GPU. With gpu_profile unset, this is whole devices; with gpu_profile set, this is the count of MIG instances of that profile (decision D5).
min 0
gpu_kindstring
Optional GPU model to match (e.g. "a100"). Empty matches any kind on a host that has GPUs.
gpu_profilestring
Optional MIG profile in mig-parted vocabulary (e.g. "1g.10gb"). When set, gpus counts MIG instances of this profile rather than whole devices, and the qemu host agent attaches them via vfio-pci sysfsdev (decision D5).
imagestring
Optional named base rootfs for the provider to boot from (resolved by the host agent against its named-rootfs directory). Empty means the provider's default base image.
regionstring
host_idstring
Pins the environment to an exact host id (the Fusefile's placement.host). A pin is a hard gate, not an override: the host must still be active, run the right backend, and fit the request. An unknown host id is rejected with 404 before any VM is created.
labelsobject
Placement label selectors (the Fusefile's placement.labels). Every pair must match the target host's operator-declared labels. A selector that matches no host is rejected with 503, never queued.
max_runtime_secondsinteger<int64>
Leak-detection ceiling for this task. Zero means "use the fleet default". The orchestrator tears down tasks that exceed this age with no state transitions.
idle_timeout_secondsinteger<int64>
Destroys the environment once it has gone this long with no exec and no attach session. Zero means "use the fleet default", which is no idle expiry unless the operator configured one. Measured from the last exec or attach, not from create, and must be at least 60 (idle detection runs on the reconcile loop). In-guest CPU use and traffic on exposed ports are not observed.
manifest_inlinestring
Optional raw manifest JSON, base64-encoded. When omitted, the orchestrator uses a minimal internal manifest.
secretsobject
Resolved key/value secrets passed to the agent.
startup_scriptstring
Optional script run inside the guest at boot.
filesobject
Guest files written before `startup_script` runs, keyed by absolute guest path with base64-encoded content. This is what a Fusefile's `copy` block compiles to. A path must be absolute and clean, and must not be under `/fuse`, which holds the guest agent's manifest, secrets and credentials; the total decoded size is capped at 512 KiB and a larger request is rejected with 413. Permissions are not carried, so an executable arrives without its bit.
startup_script_timeout_secondsinteger<int64>
Bound on `startup_script`. Omit or send 0 for the orchestrator's default (30s). The script runs synchronously inside this request, so a value above the orchestrator's configured maximum (`-max-startup-script-timeout`, 55s by default) is rejected with 400 rather than clamped.
min 0
gateway_urlstring
gateway_tokenstring
exposeExposeSpec[]
Guest ports to publish as reachable endpoints; each entry surfaces on the Environment's `endpoints`.
Show properties
Array of ExposeSpec
portintegerrequired
Guest-side port to publish.
asstring
Caller-chosen label, e.g. "http".
healthcheckobject
Environment-level readiness probe. Omit it for an environment with no probe, in which case `Environment.health` is never populated. It is not evaluated inside this request: create returns as soon as the VM is up, and the verdict arrives on later reads of the environment.
Show properties
httpHealthcheckHTTP
Show properties
portintegerrequired
Guest port to dial. The probe runs inside the guest, so this port needs no matching `expose` entry.
min 1 · max 65535
pathstring
Request path, which must start with a slash. Defaults to "/".
execstring[]
An argv run inside the guest. Exit status 0 passes. An argv rather than a shell string, so no argument can be reinterpreted by a shell.
interval_secondsinteger<int64>
Seconds between attempts. 0 for the guest agent default (10s).
min 0
timeout_secondsinteger<int64>
Bound on one attempt, in seconds. 0 for the guest agent default (2s). Attempts run one at a time, so a value above `interval_seconds` is rejected with 400 rather than silently stretching the interval.
min 0
retriesinteger
Consecutive failures that flip the verdict to failing. 0 for the guest agent default (3).
min 0
start_period_secondsinteger<int64>
Grace window from the first attempt during which failures are not counted. It ends for good once the probe passes once.
min 0
desktopobject
Graphical session geometry. Omit it for an environment with no desktop, in which case a desktop image keeps its baked default geometry.
Show properties
widthintegerrequired
Display width in pixels.
min 320 · max 3840
heightintegerrequired
Display height in pixels.
min 320 · max 3840
Responses
201Environment created.
idstringrequired
Fleet-assigned VM identifier (prefix + task_id).
statestringrequired
Allowed:provisioningrunningdrainingdestroying
task_idstringrequired
Empty when the VM is being torn down.
host_idstring
Scheduler-assigned host ID when placement uses the host registry.
urlstringrequired
host:port address where the guest agent (fused) is reachable, via per-VM DNAT. Empty before the VM is running.
specResourceSpecrequired
Hardware requirements for a VM. No lower bound is declared on cpus/ram_mb because the server does not enforce one: createEnvironment validates only task_id and the GPU fields, so a spec with `cpus: 0` / `ram_mb: 0` is accepted and scheduled. Callers should still send positive values; a strict request validator must not reject zero, or it will refuse payloads the API accepts.
Show properties
cpusinteger<int32>
min 0
ram_mbinteger<int32>
min 0
storage_gbinteger<int32>
min 0
gpusinteger<int32>
Count of GPU devices requested. Zero means no GPU. With gpu_profile unset, this is whole devices; with gpu_profile set, this is the count of MIG instances of that profile (decision D5).
min 0
gpu_kindstring
Optional GPU model to match (e.g. "a100"). Empty matches any kind on a host that has GPUs.
gpu_profilestring
Optional MIG profile in mig-parted vocabulary (e.g. "1g.10gb"). When set, gpus counts MIG instances of this profile rather than whole devices, and the qemu host agent attaches them via vfio-pci sysfsdev (decision D5).
imagestring
Optional named base rootfs for the provider to boot from (resolved by the host agent against its named-rootfs directory). Empty means the provider's default base image.
regionstring
host_idstring
Pins the environment to an exact host id (the Fusefile's placement.host). A pin is a hard gate, not an override: the host must still be active, run the right backend, and fit the request. An unknown host id is rejected with 404 before any VM is created.
labelsobject
Placement label selectors (the Fusefile's placement.labels). Every pair must match the target host's operator-declared labels. A selector that matches no host is rejected with 503, never queued.
max_runtime_secondsinteger<int64>
Leak-detection ceiling for this task. Zero means "use the fleet default". The orchestrator tears down tasks that exceed this age with no state transitions.
idle_timeout_secondsinteger<int64>
Destroys the environment once it has gone this long with no exec and no attach session. Zero means "use the fleet default", which is no idle expiry unless the operator configured one. Measured from the last exec or attach, not from create, and must be at least 60 (idle detection runs on the reconcile loop). In-guest CPU use and traffic on exposed ports are not observed.
created_atstring<date-time>required
updated_atstring<date-time>required
errorstring
Last failure message, empty on the happy path.
endpointsEndpoint[]
Published network endpoints for ports requested via the create request's `expose` list. Omitted when none.
Show properties
Array of Endpoint
asstring
Caller-chosen label from the expose request.
urlstringrequired
Reachable address, e.g. "http://203.0.113.5:41231".
portintegerrequired
The guest-side port this endpoint publishes.
healthobject
Last verdict of the environment-level healthcheck. Omitted when the environment declared no healthcheck, and omitted until the first verdict has been read back from the guest. The orchestrator refreshes it on the reconcile tick (30s by default), so it lags the guest by up to one tick.
Show properties
statestringrequired
The probe's last verdict. Deliberately separate from `Environment.state`: an unhealthy environment is still a running one, and nothing tears it down for a failing probe.
Allowed:startingpassingfailing
sincestring<date-time>
When the probe entered this state.
failuresinteger
Consecutive failed attempts. Zero while passing.
messagestring
The last attempt's failure detail. Empty while passing.
400Malformed request.
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.
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
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.
500Unexpected server error.
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.
503No registered host has room for this spec — the scheduler found no capacity, or no hosts are registered at all (code `unavailable`). This includes the GPU case: a spec asking for GPUs a host cannot satisfy lands here. There is no shutdown-rejection path; a 503 always means placement failed, so it is worth retrying once capacity frees up.
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.
Request
curl -X POST "http://localhost:8080/v1/environments" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "task_id": "string",
  "spec": {
    "cpus": 0,
    "ram_mb": 0,
    "storage_gb": 0,
    "gpus": 0,
    "gpu_kind": "string",
    "gpu_profile": "string",
    "image": "string",
    "region": "string",
    "host_id": "string",
    "labels": {},
    "max_runtime_seconds": 0,
    "idle_timeout_seconds": 0
  },
  "manifest_inline": "string",
  "secrets": {},
  "startup_script": "string",
  "files": {},
  "startup_script_timeout_seconds": 0,
  "gateway_url": "string",
  "gateway_token": "string",
  "expose": [
    {
      "port": 0,
      "as": "string"
    }
  ],
  "healthcheck": {
    "http": {
      "port": 0,
      "path": "string"
    },
    "exec": [
      "string"
    ],
    "interval_seconds": 0,
    "timeout_seconds": 0,
    "retries": 0,
    "start_period_seconds": 0
  },
  "desktop": {
    "width": 0,
    "height": 0
  }
}'
Response
{
  "id": "string",
  "state": "provisioning",
  "task_id": "string",
  "host_id": "string",
  "url": "string",
  "spec": {
    "cpus": 0,
    "ram_mb": 0,
    "storage_gb": 0,
    "gpus": 0,
    "gpu_kind": "string",
    "gpu_profile": "string",
    "image": "string",
    "region": "string",
    "host_id": "string",
    "labels": {},
    "max_runtime_seconds": 0,
    "idle_timeout_seconds": 0
  },
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "error": "string",
  "endpoints": [
    {
      "as": "string",
      "url": "string",
      "port": 0
    }
  ],
  "health": {
    "state": "starting",
    "since": "2024-01-01T00:00:00Z",
    "failures": 0,
    "message": "string"
  }
}