Create an environment

Provisions an environment under the identifier the caller names, on the one official image, and runs the caller’s setup script inside it once. Idempotent on that identifier when the existing machine’s setup state is recorded: such an id is answered 200 with the environment that exists, not 409 and not a second container — a client that lost the response to its first call may repeat it without paying twice. A setup-carrying create that meets a machine whose setup state was never recorded is refused rather than adopted: nobody can say whether that machine’s toolchain exists. A setup script that fails or runs past the host’s bound leaves the environment unusable carrying its own output as the cause, rather than a healthy-looking environment missing a toolchain.

POST /v1/environments

Create an environment

cURL

curl --request POST \
  --url https://api.example.com/v1/environments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "build-box",
  "repository": "acme/widgets",
  "setupScript": "set -eux\napt-get update && apt-get install -y --no-install-recommends make\n"
}
'

200

{
  "id": "build-box",
  "state": "ready",
  "image": "ghcr.io/lerianstudio/narya-sandbox@sha256:3f7a1c2b9d4e5f60718293a4b5c6d7e8f9012345678901234567890abcdefabcd",
  "setup": {
    "outcome": "succeeded",
    "output": "+ go version\ngo version go1.26.0 linux/amd64\n"
  },
  "createdAt": "2026-08-29T09:12:00.000Z"
}

Autorizações

Authorization · string · header · obrigatório

Enforced on every transport, with no exempt operation. A person's request must carry a JWT issued by the configured identity provider, which the host verifies itself against that issuer's key set: signature, issuer, expiry, and the person and organisation it names. Requests without a valid one receive 401 NRY-0011 — except a request with no token on a laptop's socket from the OS user the kernel names as the host's own, which is that machine's user.

Corpo

application/json

Request to provision an environment. No image is named: there is one official image, and the customer's own tooling arrives as the script below, on top of it.

id · string · obrigatório

An environment's identifier, chosen by whoever creates it and unique on this host. It travels as one path segment, so its shape is bounded to what a path segment carries unchanged, exactly as a monitor's name is: a "/" would address no route and a "?" or "#" would end the segment early and address something else. One beginning conversation- is a hosted home's own, and a create naming it is 422.

Required string length: 1 - 64

Pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$

setupScript · string

A script run once inside the new environment, after the image is up and before any session uses it — where a customer's own toolchain arrives. It runs bounded in time; a non-zero exit or a run past the bound leaves the environment unusable with this script's own output as the cause, rather than an environment that looks healthy and cannot build anything.

Maximum string length: 65536

repository · string

A repository this organisation selected when it installed Narya's GitHub App, as owner/name. The host clones it into the environment's workspace BEFORE the environment's own machine exists, so the machine holds the code and never the credential that fetched it: the clone runs in a throwaway Lerian container over the same workspace, as the same unprivileged user the environment runs as, and the short-lived installation token lives only for that one command. The clone happens before the setup script, so a script can build what was just cloned. A repository that is not in the installed set, an organisation that has connected no installation, and an installation its owner uninstalled or suspended on GitHub, are refused before any machine is made, and the refusal names the connect gesture. A clone that fails leaves the environment unusable with the cause as its setup output, exactly as a failed setup script does. Omit it for an environment that starts empty.

Maximum string length: 200

Pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*/[A-Za-z0-9][A-Za-z0-9._-]*$

Resposta

200

application/json

The environment that already existed under this identifier. Nothing was provisioned and no setup script ran.

A place a session's code lives and its commands run. The host's own machine is not one of these — it is what a session gets by naming none.

id · string · obrigatório

An environment's identifier, chosen by whoever creates it and unique on this host. It travels as one path segment, so its shape is bounded to what a path segment carries unchanged, exactly as a monitor's name is: a "/" would address no route and a "?" or "#" would end the segment early and address something else. One beginning conversation- is a hosted home's own, and a create naming it is 422.

Required string length: 1 - 64

Pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$

state · enum<string> · obrigatório

Whether an environment is answering, and — when it is not — whether waiting is the right move. The distinction is the whole point: a session waiting on an unreachable environment looks identical to a slow one otherwise, and what the person does next depends entirely on which it is. ready — answering; work proceeds. degraded — not answering right now and expected back: a restart or a dropped connection, which the host retries so the next call may simply succeed, or a container stopped outside narya, which the next turn starts. gone — destroyed, its name taken by another environment since, or the runtime no longer has it. A hosted home also removes a container nothing has used for 15 minutes and keeps its disks, the workspace and its restore points, and so does a person's own home for a conversation's own conversation-<sessionId>; it reads gone until a turn needs it. A session bound to it is then given a new container on its next turn, over the disks the old one left when those are still there, and is told which; on a person's own home a named environment that is gone needs a new one. unusable — its setup did not succeed; setup says what happened.

Opções disponíveis: ready, degraded, gone, unusable

image · string · obrigatório

The immutable digest of the image this environment actually runs, pinned when it was created and never floated afterwards. Reconnecting after a host restart, and replacing an environment that was lost, both ask for this digest again, so an environment that worked yesterday is the same environment today. There is one official image, which is why nothing supplies this on creation.

Maximum string length: 512

createdAt · string<date-time> · obrigatório

setup · object

What the setup script did, absent when none was supplied.

Show child attributes