Get an environment

One environment with the image digest it runs, whether it is answering, and what its setup script did. This is how a client tells a session waiting on an unreachable environment from a session that is merely slow.

GET /v1/environments/{environmentId}

Get an environment

cURL

curl --request GET \
  --url https://api.example.com/v1/environments/{environmentId} \
  --header 'Authorization: Bearer <token>'

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.

Parâmetros de caminho

environmentId · string · obrigatório

The environment's identifier. 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._-]*$

Resposta

200

application/json

The environment.

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