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.
huge_pagesboolean
Back guest memory with 2M pages. The host must have that much memory reserved as hugepages, or the create answers 409. Fixed for the life of the environment, and required for a lazy migrate.
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".
protocolstring
Transport to publish this port on. A forwarding rule is installed per transport, so a service that speaks both needs two entries. Omitted means tcp, which is what every request written before this field existed meant.
default: "tcp"
Allowed:tcpudp
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
wmstring
Window manager to run. Omit to keep the image's baked default. An image that does not carry the named window manager keeps its default; ComputerDisplay.wm reports the one actually running.
Allowed:mutterxfwm4openbox
egressobject
Outbound networking policy. Omit it for direct egress, which is also what an explicit `{"mode": "direct"}` means; the two produce identical behaviour and identical stored state. An unknown `provider` is refused with 400 before any environment exists, and a backend that fails to come up is a failed create with no surviving environment.
Show properties
modestring
`direct` is NAT straight out of the host, exactly the behaviour of an environment that never mentions egress. `proxy` routes every outbound connection through a backend the orchestrator provisions, health-checks and tears down. In proxy mode the host installs no direct route at all, so a workload that ignores the proxy gets no egress rather than direct egress.
default: "direct"
Allowed:directproxy
providerstring
The backend, required for `proxy`. The orchestrator refuses a name it has not registered, and the error lists the ones it has. `mock` is an in-process socks5 backend for local development that provides no privacy or isolation.
protocolstring
How the workload talks to the proxy. Proxy mode leaves the guest with no working local DNS by design, so a client must resolve names at the proxy: `socks5h://`, or http CONNECT, which always does.
default: "socks5"
Allowed:socks5http
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.
huge_pagesboolean
Back guest memory with 2M pages. The host must have that much memory reserved as hugepages, or the create answers 409. Fixed for the life of the environment, and required for a lazy migrate.
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".
protocolstring
The transport this endpoint was actually published on, which is not always what was requested: a host agent too old to know about the field publishes tcp and omits this. Read it rather than assuming the request was honoured.
Allowed:tcpudp
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.
egressobject
The resolved outbound policy. Always present on a server that knows about egress: an environment created without asking reports `direct`, so a caller can tell "not proxied" from "this server predates the field".
Show properties
modestringrequired
Allowed:directproxy
providerstring
The backend serving this environment. Proxy only.
protocolstring
Proxy only.
Allowed:socks5http
endpointstring
The proxy url the workload was handed, e.g. `socks5h://10.200.3.1:1080`. A host-local address useless to anyone not already inside the sandbox, and never a credential. Proxy only.
healthobject
The endpoint's last probe verdict. Proxy only, and `unknown` until the reconcile tick (30s by default) has probed it once. An unhealthy proxy reports and nothing acts on it: the environment keeps running with no egress, never with direct egress.
Show properties
statestringrequired
Allowed:unknownhealthyunhealthy
reasonstring
The backend-level failure, e.g. `dial tcp 10.200.3.1:1080: connection refused`. Empty while healthy. Never a destination hostname or anything drawn from the sandbox's traffic.
checked_atstring<date-time>
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": {},
    "huge_pages": true,
    "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",
      "protocol": "tcp"
    }
  ],
  "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,
    "wm": "mutter"
  },
  "egress": {
    "mode": "direct",
    "provider": "string",
    "protocol": "socks5"
  }
}'
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": {},
    "huge_pages": true,
    "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",
      "protocol": "tcp",
      "port": 0
    }
  ],
  "health": {
    "state": "starting",
    "since": "2024-01-01T00:00:00Z",
    "failures": 0,
    "message": "string"
  },
  "egress": {
    "mode": "direct",
    "provider": "string",
    "protocol": "socks5",
    "endpoint": "string",
    "health": {
      "state": "unknown",
      "reason": "string",
      "checked_at": "2024-01-01T00:00:00Z"
    }
  }
}