Administer a fleet 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
  }
}
'

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
    } }
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
    }
  })
};

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
    ]
  ]),
  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}")

	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}")
  .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}"

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

{
  "admin_state": "active",
  "id": "<string>",
  "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
  },
  "selftest_requested_at": 123
}

{
  "detail": "<string>",
  "docs_uri": "<string>",
  "error_code": "<string>",
  "request_id": "<string>",
  "title": "<string>",
  "action_id": "<string>",
  "current_state": "<string>",
  "etag": "<string>",
  "gate_id": "<string>",
  "missing_secrets": [
    "<string>"
  ],
  "outcome": "<string>",
  "resolved_at": 123,
  "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>",
  "missing_secrets": [
    "<string>"
  ],
  "outcome": "<string>",
  "resolved_at": 123,
  "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>",
  "missing_secrets": [
    "<string>"
  ],
  "outcome": "<string>",
  "resolved_at": 123,
  "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>",
  "missing_secrets": [
    "<string>"
  ],
  "outcome": "<string>",
  "resolved_at": 123,
  "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>",
  "missing_secrets": [
    "<string>"
  ],
  "outcome": "<string>",
  "resolved_at": 123,
  "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>",
  "missing_secrets": [
    "<string>"
  ],
  "outcome": "<string>",
  "resolved_at": 123,
  "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>",
  "missing_secrets": [
    "<string>"
  ],
  "outcome": "<string>",
  "resolved_at": 123,
  "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>",
  "missing_secrets": [
    "<string>"
  ],
  "outcome": "<string>",
  "resolved_at": 123,
  "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>",
  "missing_secrets": [
    "<string>"
  ],
  "outcome": "<string>",
  "resolved_at": 123,
  "resolved_by": "<string>",
  "user_message": "<string>"
}

Fleet

Administer a fleet runner

Platform-admin mutation on a single runner. The body carries exactly one of action or assigned_policy. action moves the admin state: cordon to cordoned, drain to draining, revoke to revoked. Revoked is terminal; a revoked runner cannot transition back. self_test moves no state. It records a request for the runner to test its own sandbox. The host picks the request up on its next heartbeat and answers on a later one. The reply is the recorded request, never a verdict. A revoked runner refuses it with 409 UZ-RUN-018, since it will never heartbeat again. assigned_policy reassigns the runner’s policy, and the host picks it up on its next heartbeat. Sending the same policy again changes nothing and records no event.

PATCH

fleets

runners

{runner_id}

Administer a fleet 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
  }
}
'

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
    } }
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
    }
  })
};

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
    ]
  ]),
  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}")

	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}")
  .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}"

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

{
  "admin_state": "active",
  "id": "<string>",
  "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
  },
  "selftest_requested_at": 123
}

{
  "detail": "<string>",
  "docs_uri": "<string>",
  "error_code": "<string>",
  "request_id": "<string>",
  "title": "<string>",
  "action_id": "<string>",
  "current_state": "<string>",
  "etag": "<string>",
  "gate_id": "<string>",
  "missing_secrets": [
    "<string>"
  ],
  "outcome": "<string>",
  "resolved_at": 123,
  "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>",
  "missing_secrets": [
    "<string>"
  ],
  "outcome": "<string>",
  "resolved_at": 123,
  "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>",
  "missing_secrets": [
    "<string>"
  ],
  "outcome": "<string>",
  "resolved_at": 123,
  "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>",
  "missing_secrets": [
    "<string>"
  ],
  "outcome": "<string>",
  "resolved_at": 123,
  "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>",
  "missing_secrets": [
    "<string>"
  ],
  "outcome": "<string>",
  "resolved_at": 123,
  "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>",
  "missing_secrets": [
    "<string>"
  ],
  "outcome": "<string>",
  "resolved_at": 123,
  "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>",
  "missing_secrets": [
    "<string>"
  ],
  "outcome": "<string>",
  "resolved_at": 123,
  "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>",
  "missing_secrets": [
    "<string>"
  ],
  "outcome": "<string>",
  "resolved_at": 123,
  "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>",
  "missing_secrets": [
    "<string>"
  ],
  "outcome": "<string>",
  "resolved_at": 123,
  "resolved_by": "<string>",
  "user_message": "<string>"
}

Authorizations

Authorization

string

header

required

Obtain a token via the CLI auth flow (POST /v1/auth/sessions) or GitHub OAuth

Path Parameters

runner_id

string

required

UUIDv7 of the runner.

Body

application/json

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

Exactly one of action or assigned_policy; both or neither is a 400.

action

null | enum<string>

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

Available options:

cordon,

drain,

revoke,

rotate,

self_test

assigned_policy

null | object

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

Show child attributes

Response

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

admin_state

enum<string>

required

Its state after the change.

Available options:

active,

cordoned,

draining,

drained,

revoked

string

required

The runner that changed.

assigned_policy

null | object

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

Show child attributes

selftest_requested_at

integer<int64> | null

When the self-test request was recorded, epoch milliseconds.

The reply is the REQUEST, never a verdict — the daemon picks the ask up on its next beat, so a result cannot exist yet. Returning the instant lets a reader age the pending state instead of spinning with no clock.

Overview

Health

Authentication

API keys

Tenants

Tenant provider

Tenant balance

Tenant models

Fleet

Runner plane

Model Library

Workspaces

Workspace preferences

Secrets

Connectors

Approvals

Fleets

Fleet library

Fleet messages

Fleet memories

Fleet schedules

Fleet events

Integration grants

Webhooks

Admin

Administer a fleet runner

Authorizations

Path Parameters

Body

Response