> ## 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. # 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. ## OpenAPI ````yaml https://raw.githubusercontent.com/agentsfleet/agentsfleet/main/public/openapi.json post /v1/runners/me/heartbeats 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/runners/me/heartbeats: post: tags: - Runners summary: Send a heartbeat and receive settings description: >- 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. operationId: runner_heartbeat requestBody: content: application/json: schema: oneOf: - $ref: '#/components/schemas/HeartbeatRequest' - type: 'null' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/HeartbeatResponse' '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' '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: - RunnerBearerAuth: [] components: schemas: HeartbeatRequest: type: object description: |- `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. required: - holds - closing properties: capability_report: oneOf: - $ref: '#/components/schemas/CapabilityReport' description: >- What this host can enforce, when the probe result is being reported. - type: 'null' closing: type: boolean description: >- True when the runner's held-sandbox list is final. Any previously held sandbox missing from `holds` is released immediately. holds: type: array items: type: string maxLength: 36 minLength: 36 description: |- 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. maxItems: 64 selftest: oneOf: - $ref: '#/components/schemas/SelftestReport' description: >- A verdict produced since the last beat, by request or by startup probe. - type: 'null' additionalProperties: false HeartbeatResponse: type: object description: >- `POST /v1/runners/me/heartbeats` reply. Carries the current assignment on EVERY beat, so a dashboard change reaches the host within one interval. required: - status - assigned_policy - degraded - selftest_requested - release_holds - heartbeat_interval_ms properties: assigned_policy: $ref: '#/components/schemas/AssignedPolicy' description: The runner's current assignment. degraded: type: boolean description: Whether the row reads degraded. degraded_reason: type: - string - 'null' description: Why it reads degraded. heartbeat_interval_ms: type: integer format: int32 description: >- Milliseconds to wait before the next heartbeat. Use this server-provided interval to avoid being marked offline. minimum: 0 release_holds: type: array items: type: string description: >- Fleets 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. selftest_requested: type: boolean description: |- An operator asked this runner to self-test. Rides the beat like the assignment does — one interval, no second endpoint, no host visit. status: $ref: '#/components/schemas/HeartbeatStatus' description: Whether to keep working, drain, or stop. 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. CapabilityReport: type: object description: | What this host can actually enforce. required: - landlock - seccomp - cgroup_controllers - bubblewrap - egress_enforcement properties: bubblewrap: type: boolean description: The sandbox launcher is available. build_id: type: - string - 'null' description: >- Source digest compiled into the reporting runner; absent for an unbound build. cgroup_controllers: type: array items: type: string description: Controllers present in the delegated cgroup's subtree control. egress_enforcement: type: boolean description: >- Whether the operating system can restrict outgoing network access to allowed hosts. landlock: type: boolean description: Filesystem isolation is available. seccomp: type: boolean description: System-call filtering is available. additionalProperties: false SelftestReport: type: object description: |- One probe run and the verdict it reached. The tier and policy travel with the verdict. Compare them against the runner's current values to tell a stale result from a live one. required: - checks - all_ok - sandbox_tier - network_policy properties: all_ok: type: boolean description: Whether every check passed. checks: type: array items: $ref: '#/components/schemas/SelftestCheck' description: Every check the probe ran. network_policy: type: string description: Outgoing network access policy in effect during the self-test. sandbox_tier: type: string description: The tier in force when the probe ran. additionalProperties: false 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 HeartbeatStatus: type: string description: Heartbeat reply status. enum: - ok - drain - stop SelftestCheck: type: object description: >- One self-test check's verdict. `detail` is prose even when `ok`: every passing check carries a line, and a whitespace-free cause reads to an operator as a leaked internal identifier. required: - name - ok - detail properties: detail: type: string description: Why, in prose. name: type: string description: What was checked. ok: type: boolean description: Whether it passed. additionalProperties: false 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: RunnerBearerAuth: type: http scheme: bearer bearerFormat: agt_r description: Runner token beginning with agt_r, returned once by POST /v1/runners ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.