> ## Documentation Index
> Fetch the complete documentation index at: https://docs.use.observer/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent and cloud boundary

> What crosses the network and what does not.

The Observer Agent is the only component that runs inside your
network. The cloud sits across an HTTPS boundary and never reaches
back into your network. This page is the explicit description of
what crosses that boundary and what stays put.

## What the agent sends to the cloud

```text theme={null}
POST /api/agent/heartbeat
  every ~30 seconds. Self-state report: agent version and build,
  uptime, the host name, queue depth, active source types, and
  the names of any custom probes you registered (not their
  descriptions). No readings, queries or secrets. See the heartbeat payload
  reference.

GET /api/agent/metrics-definitions
  Pull of the metric definitions assigned to this agent: at
  start, whenever a heartbeat reports that the definitions
  changed, every 30 seconds for the first 10 minutes while the
  agent has none, and every 5 minutes as a backstop. A change
  in the console reaches the agent in about 30 seconds. The
  response is the canonical list the agent schedules against.

POST /api/agent/receiver/batch
  drains the local queue, up to 100 readings per request. Each
  reading is one row:
    { metric_id, value, status, timestamp, reason? }
  reason is a short code (for example ETIMEDOUT or
  body_mismatch) set when the probe produced no value.

GET  /api/agent/work/jobs
POST /api/agent/work/jobs/<id>/result
  agent 1.7.0 and later, polled about every 5 seconds. Picks up
  jobs you start from the console's metric form or the API: a
  one-off probe test of a draft metric, and CloudWatch "list
  available metrics" requests. A probe test returns only the
  value, the verdict, the latency and a reason code. A metric
  listing returns metric names and dimensions, no values.

GET  /api/agent/work/cloudwatch-list-metrics
POST /api/agent/work/cloudwatch-list-metrics/<id>/result
  agents before 1.7.0, or a cloud without the job endpoint, and
  only while at least one CloudWatch metric is assigned. Same
  "list available metrics" requests as above.

POST /api/agent/heartbeat-relay (optional)
  only when HEARTBEAT_RELAY_ENABLED=true. Forwards heartbeat
  pings that local jobs sent to the agent's heartbeat relay.

POST /api/agent/log (optional)
  only when BROADCAST_LOGS=true. Forwards agent log lines at or
  above LOG_BROADCAST_LEVEL to the console's live log viewer,
  which stores nothing. PromQL query
  strings are always redacted to a SHA-256 prefix and length.
```

That is the entire surface. There are no other calls to the cloud.
The agent's only other network traffic is the probes you define,
sent to the targets you name.

## What the agent does not send

* Raw PromQL query strings.
* Raw HTTP request bodies, response bodies, or response headers.
* DNS resolver responses. A configured `expected_value` is matched
  on the agent; only the reading is sent.
* TLS certificate chains or certificate details. Only the reading
  (days until expiry) is sent.
* Credentials. Secret values named by `*_ref` fields stay on the
  agent host: database connection strings, mTLS certificates and
  keys, auth tokens, secret request headers (`header_refs`), and
  secret gRPC metadata (`metadata_refs`). The cloud stores only
  the env var names; the agent reads the values locally at probe
  time.
* Raw query responses: result sets, response bodies, and log
  lines behind a reading stay on the host.
* Agent logs, unless you set `BROADCAST_LOGS=true` (off by
  default).
* Any metric series outside the explicit metric definitions.

## What the cloud sends to the agent

The response to `GET /api/agent/metrics-definitions`, the heartbeat
acknowledgement, and pending jobs: probe tests (a draft
`source_type`, `source_config` and thresholds) and CloudWatch "list
available metrics" requests. The definitions response shape
is the projection in the public `@observer/protocol` package's
`MetricDefinition` type. The heartbeat acknowledgement carries a
few counters and an opaque definitions version string (see the
[heartbeat payload reference](https://docs.use.observer/agent/reference/heartbeat-payload.md));
it never carries instructions or configuration beyond telling the
agent that its definitions changed.

The cloud has no path back into your network. It cannot pull from
your Prometheus, hit your endpoints, or query your DNS. Every
probe runs from the agent's vantage point.

> [!NOTE]
>
> **Why this matters**
>
> The agent fits networks where outbound HTTPS is the only allowed
> path: one connection to the cloud plus the probe targets you
> define, and no inbound connections.

## Trust assumptions

* The agent trusts the cloud's TLS certificate by default. Set
  `SKIP_SSL_VERIFICATION=true` in development only.
* The cloud trusts the agent only after the agent presents a
  valid `AGENT_KEY`. Keys are bound to a single agent identity
  and a single organisation.
* A compromised agent key affects only that agent's pushes.
  The cloud restricts each request to the agent's own
  organisation; a stolen key cannot read or write across
  tenants.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.