> ## 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. # Report liveness, receive assignment > Liveness up, configuration down. The assignment rides every reply. An operator's dashboard change therefore reaches the host within one interval, and nobody visits the host. An unreadable body is read as `no report this beat` and the beat still counts. A host must not be able to fail its own liveness by sending nonsense. ## OpenAPI ````yaml https://raw.githubusercontent.com/agentsfleet/agentsfleet/main/public/openapi.json post /v1/runners/me/heartbeats openapi: 3.1.0 info: title: agentsfleet Control Plane 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: Report liveness, receive assignment description: >- Liveness up, configuration down. The assignment rides every reply. An operator's dashboard change therefore reaches the host within one interval, and nobody visits the host. An unreadable body is read as `no report this beat` and the beat still counts. A host must not be able to fail its own liveness by sending nonsense. operationId: runner_heartbeat requestBody: content: application/json: schema: oneOf: - type: 'null' - $ref: '#/components/schemas/HeartbeatRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/HeartbeatResponse' '401': description: No credential, or one this route does not accept content: application/problem+json: schema: $ref: '#/components/schemas/ProblemBody' '403': description: The credential is good and lacks the capability this route requires content: application/problem+json: schema: $ref: '#/components/schemas/ProblemBody' '413': description: The payload is over this route's ceiling content: application/problem+json: schema: $ref: '#/components/schemas/ProblemBody' '429': description: The instance is at its ceiling content: application/problem+json: schema: $ref: '#/components/schemas/ProblemBody' '500': description: The daemon failed to answer content: application/problem+json: schema: $ref: '#/components/schemas/ProblemBody' '503': description: A dependency this route needs is unreachable 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. Both fields default to absent so an older runner's empty body still parses. properties: capability_report: oneOf: - type: 'null' - $ref: '#/components/schemas/CapabilityReport' description: >- What this host can enforce, when the probe result is being reported. selftest: oneOf: - type: 'null' - $ref: '#/components/schemas/SelftestReport' description: >- A verdict produced since the last beat, by request or by startup probe. 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. A null assignment means a row predating the policy columns: the runner then fails closed and refuses to lease. required: - status - degraded - selftest_requested properties: assigned_policy: oneOf: - type: 'null' - $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. 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. 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.' missing_secrets: type: - array - 'null' items: type: string description: 'On a 424 only: the credentials this workspace has yet to store.' 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: - integer - 'null' format: int64 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. cgroup_controllers: type: array items: type: string description: Controllers present in the delegated cgroup's subtree control. egress_enforcement: type: boolean description: Kernel-enforced egress allowlisting is available. landlock: type: boolean description: Filesystem isolation is available. seccomp: type: boolean description: System-call filtering is available. 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: The egress posture in force when the probe ran. sandbox_tier: type: string description: The tier in force when the probe ran. AssignedPolicy: type: object description: The isolation, egress and concurrency settings assigned to one 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: Egress posture to apply. registry_allowlist: type: array items: type: string description: >- Operator registry baseline merged into each lease's egress allowlist. Empty means the runner substitutes its own default registry set. 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. 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: >- Egress posture assigned per runner, named so the behaviour reads off the value. 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: The opaque agt_r token minted when the runner enrols (POST /v1/runners) ````