Manage a runner

curl --request PATCH \
  --url https://api.agentsfleet.net/v1/fleets/runners/{runner_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "assigned_policy": {
    "extra_binds": [
      {
        "note": "<string>",
        "path": "<string>"
      }
    ],
    "registry_allowlist": [
      "<string>"
    ],
    "worker_count": 1
  },
  "labels": [
    "<string>"
  ]
}
'

import requests

url = "https://api.agentsfleet.net/v1/fleets/runners/{runner_id}"

payload = {
    "assigned_policy": {
        "extra_binds": [
            {
                "note": "<string>",
                "path": "<string>"
            }
        ],
        "registry_allowlist": ["<string>"],
        "worker_count": 1
    },
    "labels": ["<string>"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    assigned_policy: {
      extra_binds: [{note: '<string>', path: '<string>'}],
      registry_allowlist: ['<string>'],
      worker_count: 1
    },
    labels: ['<string>']
  })
};

fetch('https://api.agentsfleet.net/v1/fleets/runners/{runner_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.agentsfleet.net/v1/fleets/runners/{runner_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'assigned_policy' => [
        'extra_binds' => [
                [
                                'note' => '<string>',
                                'path' => '<string>'
                ]
        ],
        'registry_allowlist' => [
                '<string>'
        ],
        'worker_count' => 1
    ],
    'labels' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentsfleet.net/v1/fleets/runners/{runner_id}"

	payload := strings.NewReader("{\n  \"assigned_policy\": {\n    \"extra_binds\": [\n      {\n        \"note\": \"<string>\",\n        \"path\": \"<string>\"\n      }\n    ],\n    \"registry_allowlist\": [\n      \"<string>\"\n    ],\n    \"worker_count\": 1\n  },\n  \"labels\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.agentsfleet.net/v1/fleets/runners/{runner_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"assigned_policy\": {\n    \"extra_binds\": [\n      {\n        \"note\": \"<string>\",\n        \"path\": \"<string>\"\n      }\n    ],\n    \"registry_allowlist\": [\n      \"<string>\"\n    ],\n    \"worker_count\": 1\n  },\n  \"labels\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.agentsfleet.net/v1/fleets/runners/{runner_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"assigned_policy\": {\n    \"extra_binds\": [\n      {\n        \"note\": \"<string>\",\n        \"path\": \"<string>\"\n      }\n    ],\n    \"registry_allowlist\": [\n      \"<string>\"\n    ],\n    \"worker_count\": 1\n  },\n  \"labels\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "status": "active",
  "assigned_policy": {
    "extra_binds": [
      {
        "mode": "read_only",
        "note": "<string>",
        "path": "<string>"
      }
    ],
    "network_policy": "allow_all",
    "registry_allowlist": [
      "<string>"
    ],
    "sandbox_tier": "landlock_full",
    "worker_count": 1
  },
  "labels": [
    "<string>"
  ],
  "selftest_requested_at": "2023-11-07T05:31:56Z"
}

{
  "detail": "<string>",
  "docs_uri": "<string>",
  "error_code": "<string>",
  "request_id": "<string>",
  "title": "<string>",
  "action_id": "<string>",
  "current_state": "<string>",
  "etag": "<string>",
  "gate_id": "<string>",
  "outcome": "<string>",
  "resolved_at": "2023-11-07T05:31:56Z",
  "resolved_by": "<string>",
  "user_message": "<string>"
}

{
  "detail": "<string>",
  "docs_uri": "<string>",
  "error_code": "<string>",
  "request_id": "<string>",
  "title": "<string>",
  "action_id": "<string>",
  "current_state": "<string>",
  "etag": "<string>",
  "gate_id": "<string>",
  "outcome": "<string>",
  "resolved_at": "2023-11-07T05:31:56Z",
  "resolved_by": "<string>",
  "user_message": "<string>"
}

{
  "detail": "<string>",
  "docs_uri": "<string>",
  "error_code": "<string>",
  "request_id": "<string>",
  "title": "<string>",
  "action_id": "<string>",
  "current_state": "<string>",
  "etag": "<string>",
  "gate_id": "<string>",
  "outcome": "<string>",
  "resolved_at": "2023-11-07T05:31:56Z",
  "resolved_by": "<string>",
  "user_message": "<string>"
}

{
  "detail": "<string>",
  "docs_uri": "<string>",
  "error_code": "<string>",
  "request_id": "<string>",
  "title": "<string>",
  "action_id": "<string>",
  "current_state": "<string>",
  "etag": "<string>",
  "gate_id": "<string>",
  "outcome": "<string>",
  "resolved_at": "2023-11-07T05:31:56Z",
  "resolved_by": "<string>",
  "user_message": "<string>"
}

{
  "detail": "<string>",
  "docs_uri": "<string>",
  "error_code": "<string>",
  "request_id": "<string>",
  "title": "<string>",
  "action_id": "<string>",
  "current_state": "<string>",
  "etag": "<string>",
  "gate_id": "<string>",
  "outcome": "<string>",
  "resolved_at": "2023-11-07T05:31:56Z",
  "resolved_by": "<string>",
  "user_message": "<string>"
}

{
  "detail": "<string>",
  "docs_uri": "<string>",
  "error_code": "<string>",
  "request_id": "<string>",
  "title": "<string>",
  "action_id": "<string>",
  "current_state": "<string>",
  "etag": "<string>",
  "gate_id": "<string>",
  "outcome": "<string>",
  "resolved_at": "2023-11-07T05:31:56Z",
  "resolved_by": "<string>",
  "user_message": "<string>"
}

{
  "detail": "<string>",
  "docs_uri": "<string>",
  "error_code": "<string>",
  "request_id": "<string>",
  "title": "<string>",
  "action_id": "<string>",
  "current_state": "<string>",
  "etag": "<string>",
  "gate_id": "<string>",
  "outcome": "<string>",
  "resolved_at": "2023-11-07T05:31:56Z",
  "resolved_by": "<string>",
  "user_message": "<string>"
}

{
  "detail": "<string>",
  "docs_uri": "<string>",
  "error_code": "<string>",
  "request_id": "<string>",
  "title": "<string>",
  "action_id": "<string>",
  "current_state": "<string>",
  "etag": "<string>",
  "gate_id": "<string>",
  "outcome": "<string>",
  "resolved_at": "2023-11-07T05:31:56Z",
  "resolved_by": "<string>",
  "user_message": "<string>"
}

{
  "detail": "<string>",
  "docs_uri": "<string>",
  "error_code": "<string>",
  "request_id": "<string>",
  "title": "<string>",
  "action_id": "<string>",
  "current_state": "<string>",
  "etag": "<string>",
  "gate_id": "<string>",
  "outcome": "<string>",
  "resolved_at": "2023-11-07T05:31:56Z",
  "resolved_by": "<string>",
  "user_message": "<string>"
}

Runner administration

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.

PATCH

fleets

runners

{runner_id}

Manage a runner

curl --request PATCH \
  --url https://api.agentsfleet.net/v1/fleets/runners/{runner_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "assigned_policy": {
    "extra_binds": [
      {
        "note": "<string>",
        "path": "<string>"
      }
    ],
    "registry_allowlist": [
      "<string>"
    ],
    "worker_count": 1
  },
  "labels": [
    "<string>"
  ]
}
'

import requests

url = "https://api.agentsfleet.net/v1/fleets/runners/{runner_id}"

payload = {
    "assigned_policy": {
        "extra_binds": [
            {
                "note": "<string>",
                "path": "<string>"
            }
        ],
        "registry_allowlist": ["<string>"],
        "worker_count": 1
    },
    "labels": ["<string>"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    assigned_policy: {
      extra_binds: [{note: '<string>', path: '<string>'}],
      registry_allowlist: ['<string>'],
      worker_count: 1
    },
    labels: ['<string>']
  })
};

fetch('https://api.agentsfleet.net/v1/fleets/runners/{runner_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.agentsfleet.net/v1/fleets/runners/{runner_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'assigned_policy' => [
        'extra_binds' => [
                [
                                'note' => '<string>',
                                'path' => '<string>'
                ]
        ],
        'registry_allowlist' => [
                '<string>'
        ],
        'worker_count' => 1
    ],
    'labels' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentsfleet.net/v1/fleets/runners/{runner_id}"

	payload := strings.NewReader("{\n  \"assigned_policy\": {\n    \"extra_binds\": [\n      {\n        \"note\": \"<string>\",\n        \"path\": \"<string>\"\n      }\n    ],\n    \"registry_allowlist\": [\n      \"<string>\"\n    ],\n    \"worker_count\": 1\n  },\n  \"labels\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.agentsfleet.net/v1/fleets/runners/{runner_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"assigned_policy\": {\n    \"extra_binds\": [\n      {\n        \"note\": \"<string>\",\n        \"path\": \"<string>\"\n      }\n    ],\n    \"registry_allowlist\": [\n      \"<string>\"\n    ],\n    \"worker_count\": 1\n  },\n  \"labels\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.agentsfleet.net/v1/fleets/runners/{runner_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"assigned_policy\": {\n    \"extra_binds\": [\n      {\n        \"note\": \"<string>\",\n        \"path\": \"<string>\"\n      }\n    ],\n    \"registry_allowlist\": [\n      \"<string>\"\n    ],\n    \"worker_count\": 1\n  },\n  \"labels\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "status": "active",
  "assigned_policy": {
    "extra_binds": [
      {
        "mode": "read_only",
        "note": "<string>",
        "path": "<string>"
      }
    ],
    "network_policy": "allow_all",
    "registry_allowlist": [
      "<string>"
    ],
    "sandbox_tier": "landlock_full",
    "worker_count": 1
  },
  "labels": [
    "<string>"
  ],
  "selftest_requested_at": "2023-11-07T05:31:56Z"
}

{
  "detail": "<string>",
  "docs_uri": "<string>",
  "error_code": "<string>",
  "request_id": "<string>",
  "title": "<string>",
  "action_id": "<string>",
  "current_state": "<string>",
  "etag": "<string>",
  "gate_id": "<string>",
  "outcome": "<string>",
  "resolved_at": "2023-11-07T05:31:56Z",
  "resolved_by": "<string>",
  "user_message": "<string>"
}

{
  "detail": "<string>",
  "docs_uri": "<string>",
  "error_code": "<string>",
  "request_id": "<string>",
  "title": "<string>",
  "action_id": "<string>",
  "current_state": "<string>",
  "etag": "<string>",
  "gate_id": "<string>",
  "outcome": "<string>",
  "resolved_at": "2023-11-07T05:31:56Z",
  "resolved_by": "<string>",
  "user_message": "<string>"
}

{
  "detail": "<string>",
  "docs_uri": "<string>",
  "error_code": "<string>",
  "request_id": "<string>",
  "title": "<string>",
  "action_id": "<string>",
  "current_state": "<string>",
  "etag": "<string>",
  "gate_id": "<string>",
  "outcome": "<string>",
  "resolved_at": "2023-11-07T05:31:56Z",
  "resolved_by": "<string>",
  "user_message": "<string>"
}

{
  "detail": "<string>",
  "docs_uri": "<string>",
  "error_code": "<string>",
  "request_id": "<string>",
  "title": "<string>",
  "action_id": "<string>",
  "current_state": "<string>",
  "etag": "<string>",
  "gate_id": "<string>",
  "outcome": "<string>",
  "resolved_at": "2023-11-07T05:31:56Z",
  "resolved_by": "<string>",
  "user_message": "<string>"
}

{
  "detail": "<string>",
  "docs_uri": "<string>",
  "error_code": "<string>",
  "request_id": "<string>",
  "title": "<string>",
  "action_id": "<string>",
  "current_state": "<string>",
  "etag": "<string>",
  "gate_id": "<string>",
  "outcome": "<string>",
  "resolved_at": "2023-11-07T05:31:56Z",
  "resolved_by": "<string>",
  "user_message": "<string>"
}

{
  "detail": "<string>",
  "docs_uri": "<string>",
  "error_code": "<string>",
  "request_id": "<string>",
  "title": "<string>",
  "action_id": "<string>",
  "current_state": "<string>",
  "etag": "<string>",
  "gate_id": "<string>",
  "outcome": "<string>",
  "resolved_at": "2023-11-07T05:31:56Z",
  "resolved_by": "<string>",
  "user_message": "<string>"
}

{
  "detail": "<string>",
  "docs_uri": "<string>",
  "error_code": "<string>",
  "request_id": "<string>",
  "title": "<string>",
  "action_id": "<string>",
  "current_state": "<string>",
  "etag": "<string>",
  "gate_id": "<string>",
  "outcome": "<string>",
  "resolved_at": "2023-11-07T05:31:56Z",
  "resolved_by": "<string>",
  "user_message": "<string>"
}

{
  "detail": "<string>",
  "docs_uri": "<string>",
  "error_code": "<string>",
  "request_id": "<string>",
  "title": "<string>",
  "action_id": "<string>",
  "current_state": "<string>",
  "etag": "<string>",
  "gate_id": "<string>",
  "outcome": "<string>",
  "resolved_at": "2023-11-07T05:31:56Z",
  "resolved_by": "<string>",
  "user_message": "<string>"
}

{
  "detail": "<string>",
  "docs_uri": "<string>",
  "error_code": "<string>",
  "request_id": "<string>",
  "title": "<string>",
  "action_id": "<string>",
  "current_state": "<string>",
  "etag": "<string>",
  "gate_id": "<string>",
  "outcome": "<string>",
  "resolved_at": "2023-11-07T05:31:56Z",
  "resolved_by": "<string>",
  "user_message": "<string>"
}

Authorizations

Authorization

string

header

required

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.

Path Parameters

runner_id

string

required

Runner identifier (version 7 universally unique identifier, or UUID).

Body

application/json

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.

action

enum<string> | null

A state transition, token rotation, or self-test request. Sent alone.

Available options:

cordon,

drain,

revoke,

rotate,

self_test

assigned_policy

object | null

A policy re-assignment, which reaches the host on its next heartbeat.

Show child attributes

labels

string[] | null

Replaces all runner labels: at most 32 labels of 64 bytes each. Duplicates are removed in their original order. An empty list clears labels.

Response

PATCH /v1/fleets/runners/{id} reply.

string

required

The runner that changed.

status

enum<string>

required

Its operator state after the change.

Available options:

active,

cordoned,

draining,

drained,

revoked

assigned_policy

object | null

The assignment as stored, on the policy-update path.

Show child attributes

labels

string[] | null

The labels as stored, each once, when the request carried labels.

selftest_requested_at

string<date-time> | null

When the self-test was requested. The runner receives it on its next heartbeat and reports later; this timestamp does not indicate success.

Overview

Health

Authentication

API keys

Users

Account management

Model provider credentials

Balance and usage

Account models

Runner administration

Runner API

Model catalog

Workspaces

Private setup chats

Workspace preferences

Secrets

Connectors

Approvals

Fleets

Fleet library

Fleet messages

Fleet memories

Fleet schedules

Fleet events

Integration grants

Webhooks

Platform administration

Manage a runner

Authorizations

Path Parameters

Body

Response