Send a heartbeat and receive settings
curl --request POST \
--url https://api.agentsfleet.net/v1/runners/me/heartbeats \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"closing": true,
"holds": [
"<string>"
],
"capability_report": {
"bubblewrap": true,
"cgroup_controllers": [
"<string>"
],
"egress_enforcement": true,
"landlock": true,
"seccomp": true,
"build_id": "<string>"
},
"selftest": {
"all_ok": true,
"checks": [
{
"detail": "<string>",
"name": "<string>",
"ok": true
}
],
"network_policy": "<string>",
"sandbox_tier": "<string>"
}
}
'import requests
url = "https://api.agentsfleet.net/v1/runners/me/heartbeats"
payload = {
"closing": True,
"holds": ["<string>"],
"capability_report": {
"bubblewrap": True,
"cgroup_controllers": ["<string>"],
"egress_enforcement": True,
"landlock": True,
"seccomp": True,
"build_id": "<string>"
},
"selftest": {
"all_ok": True,
"checks": [
{
"detail": "<string>",
"name": "<string>",
"ok": True
}
],
"network_policy": "<string>",
"sandbox_tier": "<string>"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
closing: true,
holds: ['<string>'],
capability_report: {
bubblewrap: true,
cgroup_controllers: ['<string>'],
egress_enforcement: true,
landlock: true,
seccomp: true,
build_id: '<string>'
},
selftest: {
all_ok: true,
checks: [{detail: '<string>', name: '<string>', ok: true}],
network_policy: '<string>',
sandbox_tier: '<string>'
}
})
};
fetch('https://api.agentsfleet.net/v1/runners/me/heartbeats', 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/runners/me/heartbeats",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'closing' => true,
'holds' => [
'<string>'
],
'capability_report' => [
'bubblewrap' => true,
'cgroup_controllers' => [
'<string>'
],
'egress_enforcement' => true,
'landlock' => true,
'seccomp' => true,
'build_id' => '<string>'
],
'selftest' => [
'all_ok' => true,
'checks' => [
[
'detail' => '<string>',
'name' => '<string>',
'ok' => true
]
],
'network_policy' => '<string>',
'sandbox_tier' => '<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/runners/me/heartbeats"
payload := strings.NewReader("{\n \"closing\": true,\n \"holds\": [\n \"<string>\"\n ],\n \"capability_report\": {\n \"bubblewrap\": true,\n \"cgroup_controllers\": [\n \"<string>\"\n ],\n \"egress_enforcement\": true,\n \"landlock\": true,\n \"seccomp\": true,\n \"build_id\": \"<string>\"\n },\n \"selftest\": {\n \"all_ok\": true,\n \"checks\": [\n {\n \"detail\": \"<string>\",\n \"name\": \"<string>\",\n \"ok\": true\n }\n ],\n \"network_policy\": \"<string>\",\n \"sandbox_tier\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", 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.post("https://api.agentsfleet.net/v1/runners/me/heartbeats")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"closing\": true,\n \"holds\": [\n \"<string>\"\n ],\n \"capability_report\": {\n \"bubblewrap\": true,\n \"cgroup_controllers\": [\n \"<string>\"\n ],\n \"egress_enforcement\": true,\n \"landlock\": true,\n \"seccomp\": true,\n \"build_id\": \"<string>\"\n },\n \"selftest\": {\n \"all_ok\": true,\n \"checks\": [\n {\n \"detail\": \"<string>\",\n \"name\": \"<string>\",\n \"ok\": true\n }\n ],\n \"network_policy\": \"<string>\",\n \"sandbox_tier\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.agentsfleet.net/v1/runners/me/heartbeats")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"closing\": true,\n \"holds\": [\n \"<string>\"\n ],\n \"capability_report\": {\n \"bubblewrap\": true,\n \"cgroup_controllers\": [\n \"<string>\"\n ],\n \"egress_enforcement\": true,\n \"landlock\": true,\n \"seccomp\": true,\n \"build_id\": \"<string>\"\n },\n \"selftest\": {\n \"all_ok\": true,\n \"checks\": [\n {\n \"detail\": \"<string>\",\n \"name\": \"<string>\",\n \"ok\": true\n }\n ],\n \"network_policy\": \"<string>\",\n \"sandbox_tier\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"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
},
"degraded": true,
"heartbeat_interval_ms": 1,
"release_holds": [
"<string>"
],
"selftest_requested": true,
"status": "ok",
"degraded_reason": "<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 API
Send a heartbeat and receive settings
Marks the runner online and returns its assigned settings. Dashboard changes reach the runner on its next heartbeat. An unreadable report is ignored, but the heartbeat still counts.
POST
/
v1
/
runners
/
me
/
heartbeats
Send a heartbeat and receive settings
curl --request POST \
--url https://api.agentsfleet.net/v1/runners/me/heartbeats \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"closing": true,
"holds": [
"<string>"
],
"capability_report": {
"bubblewrap": true,
"cgroup_controllers": [
"<string>"
],
"egress_enforcement": true,
"landlock": true,
"seccomp": true,
"build_id": "<string>"
},
"selftest": {
"all_ok": true,
"checks": [
{
"detail": "<string>",
"name": "<string>",
"ok": true
}
],
"network_policy": "<string>",
"sandbox_tier": "<string>"
}
}
'import requests
url = "https://api.agentsfleet.net/v1/runners/me/heartbeats"
payload = {
"closing": True,
"holds": ["<string>"],
"capability_report": {
"bubblewrap": True,
"cgroup_controllers": ["<string>"],
"egress_enforcement": True,
"landlock": True,
"seccomp": True,
"build_id": "<string>"
},
"selftest": {
"all_ok": True,
"checks": [
{
"detail": "<string>",
"name": "<string>",
"ok": True
}
],
"network_policy": "<string>",
"sandbox_tier": "<string>"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
closing: true,
holds: ['<string>'],
capability_report: {
bubblewrap: true,
cgroup_controllers: ['<string>'],
egress_enforcement: true,
landlock: true,
seccomp: true,
build_id: '<string>'
},
selftest: {
all_ok: true,
checks: [{detail: '<string>', name: '<string>', ok: true}],
network_policy: '<string>',
sandbox_tier: '<string>'
}
})
};
fetch('https://api.agentsfleet.net/v1/runners/me/heartbeats', 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/runners/me/heartbeats",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'closing' => true,
'holds' => [
'<string>'
],
'capability_report' => [
'bubblewrap' => true,
'cgroup_controllers' => [
'<string>'
],
'egress_enforcement' => true,
'landlock' => true,
'seccomp' => true,
'build_id' => '<string>'
],
'selftest' => [
'all_ok' => true,
'checks' => [
[
'detail' => '<string>',
'name' => '<string>',
'ok' => true
]
],
'network_policy' => '<string>',
'sandbox_tier' => '<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/runners/me/heartbeats"
payload := strings.NewReader("{\n \"closing\": true,\n \"holds\": [\n \"<string>\"\n ],\n \"capability_report\": {\n \"bubblewrap\": true,\n \"cgroup_controllers\": [\n \"<string>\"\n ],\n \"egress_enforcement\": true,\n \"landlock\": true,\n \"seccomp\": true,\n \"build_id\": \"<string>\"\n },\n \"selftest\": {\n \"all_ok\": true,\n \"checks\": [\n {\n \"detail\": \"<string>\",\n \"name\": \"<string>\",\n \"ok\": true\n }\n ],\n \"network_policy\": \"<string>\",\n \"sandbox_tier\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", 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.post("https://api.agentsfleet.net/v1/runners/me/heartbeats")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"closing\": true,\n \"holds\": [\n \"<string>\"\n ],\n \"capability_report\": {\n \"bubblewrap\": true,\n \"cgroup_controllers\": [\n \"<string>\"\n ],\n \"egress_enforcement\": true,\n \"landlock\": true,\n \"seccomp\": true,\n \"build_id\": \"<string>\"\n },\n \"selftest\": {\n \"all_ok\": true,\n \"checks\": [\n {\n \"detail\": \"<string>\",\n \"name\": \"<string>\",\n \"ok\": true\n }\n ],\n \"network_policy\": \"<string>\",\n \"sandbox_tier\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.agentsfleet.net/v1/runners/me/heartbeats")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"closing\": true,\n \"holds\": [\n \"<string>\"\n ],\n \"capability_report\": {\n \"bubblewrap\": true,\n \"cgroup_controllers\": [\n \"<string>\"\n ],\n \"egress_enforcement\": true,\n \"landlock\": true,\n \"seccomp\": true,\n \"build_id\": \"<string>\"\n },\n \"selftest\": {\n \"all_ok\": true,\n \"checks\": [\n {\n \"detail\": \"<string>\",\n \"name\": \"<string>\",\n \"ok\": true\n }\n ],\n \"network_policy\": \"<string>\",\n \"sandbox_tier\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"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
},
"degraded": true,
"heartbeat_interval_ms": 1,
"release_holds": [
"<string>"
],
"selftest_requested": true,
"status": "ok",
"degraded_reason": "<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
Runner token beginning with agt_r, returned once by POST /v1/runners
Body
application/json
POST /v1/runners/me/heartbeats request.
The capability report rides the first beat and any beat where the probe
result changed. holds and closing ride every beat.
True when the runner's held-sandbox list is final. Any previously held sandbox missing
from holds is released immediately.
Every fleet this runner holds a frozen sandbox for, waiting for that fleet's next event. A fleet missing here is held nowhere on this runner.
Maximum array length:
64Required string length:
36What this host can enforce, when the probe result is being reported.
Show child attributes
Show child attributes
A verdict produced since the last beat, by request or by startup probe.
Show child attributes
Show child attributes
Response
OK
POST /v1/runners/me/heartbeats reply.
Carries the current assignment on EVERY beat, so a dashboard change reaches the host within one interval.
The runner's current assignment.
Show child attributes
Show child attributes
Whether the row reads degraded.
Milliseconds to wait before the next heartbeat. Use this server-provided interval to avoid being marked offline.
Required range:
x >= 0Fleets among the beat's holds the runner should let go of: no longer
active, or leased by another runner since. The runner destroys their
sandboxes.
An operator asked this runner to self-test. Rides the beat like the assignment does — one interval, no second endpoint, no host visit.
Whether to keep working, drain, or stop.
Available options:
ok, drain, stop Why it reads degraded.