NylorunDocsBeta
Runtime APIAgents

Stop a pod Agent

POST
/v1/agents/{agentId}/stop

Suspends the pod: its volume is kept, and the next turn of one of its sessions starts it again. Refused during a turn (agent_busy).

Authorization

headerAuthorizationBearer <token>

An application key of the Tenant (PUT /v1/tenant/keys/{keyId}), or Studio's key, derived from the admin key. With Nylorun-Subject and Nylorun-Scopes, it acts for that person, narrowed to those scopes. Never accepted from a browser (Origin).

Path Parameters

agentId*string

The Agent id, percent-encoded: users%2Falice%2Ftriage for users/alice/triage

Header Parameters

Nylorun-Protocol*string

The protocol version, 18

Nylorun-Subject?string

The person an application key acts for

Nylorun-Scopes?string

The subject's space-separated scopes; required with a subject

Response Body

The Agent

application/json
  1. response
id*string
manifest*string
resolvedVersion*integer
Range0 < value
manifestHash*string
tracking*string
Value in"tracking""pinned"
targetVersion*|
Range0 < value
waitingFor*|
Value in"secrets""start"null
failedVersion*|
Range0 < value
startCheck*|null
kind*string
Value in"virtual""pod""none"
harness*string
owner*string|null
labels*
state*string

working, sleeping, input_required, failing or paused; an open set

attention*array<>
desired*string
Value in"on""off"
nextWakeAt*string|null
compute*
runtime*
limits*
sessions*array<>
slots*array<>
disk?
forkedFrom*|null
lastUsedAt*string
createdAt*string
updatedAt*string
import { createClient } from "@nylorun/agents";const client = await createClient();await client.agents.stop("users/alice/assistant");
{  "id": "string",  "manifest": "string",  "resolvedVersion": 1,  "manifestHash": "string",  "tracking": "tracking",  "targetVersion": 1,  "waitingFor": "secrets",  "failedVersion": 1,  "startCheck": {    "from": 1,    "startedAt": "string"  },  "kind": "virtual",  "harness": "string",  "owner": "string",  "labels": {    "property1": "string",    "property2": "string"  },  "state": "string",  "attention": [    {      "state": "paused",      "sessionId": "string",      "reason": "string"    }  ],  "desired": "on",  "nextWakeAt": "string",  "compute": {    "state": "string",    "pod": {      "desired": "running",      "observed": "creating",      "volumeGeneration": 0,      "hostEpoch": 0,      "reason": "string",      "imageDigest": "string"    }  },  "runtime": {    "image": "string",    "resources": {      "cpus": 0,      "memory": "string"    },    "storage": "string",    "network": {      "allowedHosts": [        "string"      ]    },    "harness": "string",    "lifecycle": {      "idle": "string",      "deleteAfter": "string"    },    "setup": [      {        "command": "string",        "cwd": "string",        "timeout": "string"      }    ],    "files": [      {        "artifactId": "string",        "version": 1,        "path": "string"      }    ],    "limits": {      "artifacts": {        "fileBytes": 1,        "totalBytes": 1      },      "skills": {        "totalBytes": 1      },      "disk": {        "versionBytes": 1,        "versionEntries": 1      }    },    "secrets": {      "property1": {        "type": "environment_secret",        "allowedHosts": [          "string"        ],        "inject": {          "header": "string",          "format": "string"        },        "required": true,        "description": "string"      },      "property2": {        "type": "environment_secret",        "allowedHosts": [          "string"        ],        "inject": {          "header": "string",          "format": "string"        },        "required": true,        "description": "string"      }    }  },  "limits": {    "artifacts": {      "fileBytes": 0,      "totalBytes": 0    },    "skills": {      "totalBytes": 0    },    "disk": {      "versionBytes": 0,      "versionEntries": 0    }  },  "sessions": [    {      "id": "string",      "ownerUserId": "string",      "status": "string",      "activeTurnId": "string"    }  ],  "slots": [    {      "name": "string",      "type": "string",      "required": true,      "set": true    }  ],  "disk": {    "latestVersion": 1,    "operation": {      "kind": "snapshot",      "version": 1,      "startedAt": "string"    }  },  "forkedFrom": {    "agent": "string",    "disk": 1  },  "lastUsedAt": "string",  "createdAt": "string",  "updatedAt": "string"}

Read an Agent's events GET

`agent.created`, `.attached`, `.detached`, `.deleted`, a pod's `.running`, `.suspended`, `.relaunched`, `.lost`, `.reset` and `.failed`, `.forked`, a move's `.outdated`, `.version_changed` and `.start_failed`, and `agent.egress` for every connection its sandbox opens through egress-gate, naming the turns that were running, in order, numbered from 0, at most the Tenant's Runtime limit `environmentEventItems` (default 1000) per call: `from` reads on.

Reset a pod Agent POST

A new pod on a new, empty volume with the recipe applied; the old pod and volume are deleted. The way out of `agent_lost`. Refused during a turn (`agent_busy`).