> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentsfleet.net/llms.txt > Use this file to discover all available pages before exploring further. # Manage a runner > Requires platform administrator access. Send either `action` or an edit containing `assigned_policy`, `labels`, or both. Both edits succeed together or neither changes. Actions are `cordon`, `drain`, `revoke`, `rotate`, and `self_test`. Revocation is permanent. `rotate` returns a replacement `runner_token` once; save it and update the host. `self_test` queues a sandbox check; the runner receives it on its next heartbeat and reports later. The response confirms the request, not the result. Revoked runners return 409 `UZ-RUN-018`. Policy changes reach the runner on its next heartbeat. Repeating the current policy has no effect; revoked runners return 400. Labels replace the entire set, using enrollment limits. Duplicates are removed in their original order; an empty list clears labels. Revoked runners' labels remain editable. The response includes labels when supplied. ## OpenAPI ````yaml https://raw.githubusercontent.com/agentsfleet/agentsfleet/main/public/openapi.json patch /v1/fleets/runners/{runner_id} openapi: 3.1.0 info: title: agentsfleet API description: API for managing workspaces, fleets, triggers, and runs. contact: name: agentsfleet url: https://agentsfleet.net license: name: MIT identifier: MIT version: 1.0.0 servers: - url: https://api.agentsfleet.net description: Production security: [] paths: /v1/fleets/runners/{runner_id}: patch: tags: - Fleet summary: Manage a runner description: >- Requires platform administrator access. Send either `action` or an edit containing `assigned_policy`, `labels`, or both. Both edits succeed together or neither changes. Actions are `cordon`, `drain`, `revoke`, `rotate`, and `self_test`. Revocation is permanent. `rotate` returns a replacement `runner_token` once; save it and update the host. `self_test` queues a sandbox check; the runner receives it on its next heartbeat and reports later. The response confirms the request, not the result. Revoked runners return 409 `UZ-RUN-018`. Policy changes reach the runner on its next heartbeat. Repeating the current policy has no effect; revoked runners return 400. Labels replace the entire set, using enrollment limits. Duplicates are removed in their original order; an empty list clears labels. Revoked runners' labels remain editable. The response includes labels when supplied. operationId: patch_fleet_runner parameters: - name: runner_id in: path description: >- Runner identifier (version 7 universally unique identifier, or UUID). required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/RunnerAdminPatchRequest' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RunnerAdminPatchResponse' '400': description: The request is invalid content: application/problem+json: schema: $ref: '#/components/schemas/ProblemBody' '401': description: Authentication is missing, invalid, or not accepted by this endpoint content: application/problem+json: schema: $ref: '#/components/schemas/ProblemBody' '403': description: You do not have permission for this action content: application/problem+json: schema: $ref: '#/components/schemas/ProblemBody' '404': description: The resource was not found or is not accessible to you content: application/problem+json: schema: $ref: '#/components/schemas/ProblemBody' '409': description: The runner is revoked, so the request can never be honoured content: application/problem+json: schema: $ref: '#/components/schemas/ProblemBody' '413': description: The request body exceeds this endpoint's size limit content: application/problem+json: schema: $ref: '#/components/schemas/ProblemBody' '429': description: A request or capacity limit has been reached content: application/problem+json: schema: $ref: '#/components/schemas/ProblemBody' '500': description: An internal server error occurred content: application/problem+json: schema: $ref: '#/components/schemas/ProblemBody' '503': description: A required service is unavailable content: application/problem+json: schema: $ref: '#/components/schemas/ProblemBody' security: - BearerAuth: [] components: schemas: RunnerAdminPatchRequest: type: object description: >- `PATCH /v1/fleets/runners/{id}` body. Either an `action` alone, or an edit: `assigned_policy`, `labels`, or both, applied together or not at all. Anything else is a `400`. properties: action: oneOf: - $ref: '#/components/schemas/RunnerAdminAction' description: >- A state transition, token rotation, or self-test request. Sent alone. - type: 'null' assigned_policy: oneOf: - $ref: '#/components/schemas/AssignedPolicy' description: >- A policy re-assignment, which reaches the host on its next heartbeat. - type: 'null' labels: type: - array - 'null' items: type: string description: >- Replaces all runner labels: at most 32 labels of 64 bytes each. Duplicates are removed in their original order. An empty list clears labels. additionalProperties: false RunnerAdminPatchResponse: type: object description: '`PATCH /v1/fleets/runners/{id}` reply.' required: - id - status properties: assigned_policy: oneOf: - $ref: '#/components/schemas/AssignedPolicy' description: The assignment as stored, on the policy-update path. - type: 'null' id: type: string description: The runner that changed. labels: type: - array - 'null' items: type: string description: The labels as stored, each once, when the request carried labels. selftest_requested_at: type: - string - 'null' format: date-time description: >- When the self-test was requested. The runner receives it on its next heartbeat and reports later; this timestamp does not indicate success. status: $ref: '#/components/schemas/AdminState' description: Its operator state after the change. additionalProperties: false ProblemBody: type: object description: The body every refusal carries, under `application/problem+json`. required: - docs_uri - title - detail - error_code - request_id properties: action_id: type: - string - 'null' description: 'On that 409 only: the action the gate held.' current_state: type: - string - 'null' description: 'On a 409 only: the state that forbade the transition.' detail: type: string description: One sentence on what was refused and why. docs_uri: type: string description: Where the error code is documented. error_code: type: string description: The registry code, stable across releases. etag: type: - string - 'null' description: >- On a 412 only: the resource's current entity tag, to refetch and retry. gate_id: type: - string - 'null' description: 'On an answered approval gate''s 409 only: the gate that was answered.' outcome: type: - string - 'null' description: 'On that 409 only: the answer that stands.' request_id: type: string description: The request this refusal answers, for support. resolved_at: type: - string - 'null' format: date-time description: 'On that 409 only: when the standing answer was given.' resolved_by: type: - string - 'null' description: 'On that 409 only: who gave it.' title: type: string description: A short name for the refusal, safe to show a person. user_message: type: - string - 'null' description: A curated sentence for end users, where the code has one. RunnerAdminAction: type: string description: >- Platform-operator mutation actions. Rotation and self-test are operations rather than state transitions. They ride the same endpoint because they share the operator scope and the exactly-one-of body guard with the transition actions. enum: - cordon - drain - revoke - rotate - self_test AssignedPolicy: type: object description: >- Sandbox isolation, outgoing network access, and concurrency settings assigned to this runner. required: - sandbox_tier - network_policy - registry_allowlist - worker_count - extra_binds properties: extra_binds: type: array items: $ref: '#/components/schemas/ExtraBind' description: Extra host paths bound into every lease's sandbox. network_policy: $ref: '#/components/schemas/RunnerNetworkPolicy' description: Outgoing network access policy to apply. registry_allowlist: type: array items: type: string description: >- Default package registries added to each assignment's allowed network hosts. An empty list uses the runner's defaults. sandbox_tier: $ref: '#/components/schemas/SandboxTier' description: Isolation strength to apply. worker_count: type: integer format: int32 description: Concurrent workers the runner may start. Clamped on both sides. minimum: 0 AdminState: type: string description: >- Administrator-selected runner state. Only `Active` permits runner API requests. enum: - active - cordoned - draining - drained - revoked ExtraBind: type: object description: >- One host path bound into every lease's sandbox, in addition to the baseline. An operator may ADD a path a host needs; never remove or re-mode one the sandbox depends on. required: - path - mode - note properties: mode: $ref: '#/components/schemas/BindMode' description: Whether the bind is writable. note: type: string description: Operator note explaining why the bind exists. path: type: string description: Host path to bind. RunnerNetworkPolicy: type: string description: Outgoing network access policy assigned to a runner. enum: - allow_all - deny_all_egress - allow_list_egress SandboxTier: type: string description: The isolation strength assigned to a runner. enum: - landlock_full - container_nested - dev_none BindMode: type: string description: Whether an operator-added bind is writable. enum: - read_only - read_write securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Send a dashboard session token, an account API key (`agt_t`), or a command-line credential (`afc_`) as a Bearer token. Each endpoint lists accepted credential types. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.