Monitor a device runtime

EdgeRuntime adds periodic resource monitoring, a health endpoint, and watchdog signals around a supplied Agent. Your application still decides when to accept work, when to heartbeat, and how to respond to a timeout. It does not restart the Agent, change its model, shed tools, or enforce a process-memory limit. Start with a working device application, then make the host’s response to these signals explicit.

Quick start

This host integration factory borrows an existing Agent. It pauses admission when the runtime reports degradation and asks a host-supplied supervisor to handle watchdog timeouts. Calling it starts monitoring and the health server; the caller owns both shutdown and the Agent’s lifetime.

import type { Agent } from "@agentium/core";
import { EdgeRuntime, type EdgePreset } from "@agentium/edge";

export async function monitorDevice(
  agent: Agent,
  preset: EdgePreset,
  requestRestart: (reason: string) => void,
) {
  let accepting = true;
  let restartRequested = false;
  const runtime = new EdgeRuntime({
    agent,
    preset,
    healthPort: 9090,
    onWatchdogRestart(reason) {
      accepting = false;
      if (!restartRequested) {
        restartRequested = true;
        requestRestart(reason);
      }
    },
  });
  runtime.on("degraded", () => { accepting = false; });
  runtime.on("recovered", () => {
    if (!restartRequested) accepting = true;
  });
  try {
    await runtime.start();
  } catch (error) {
    await runtime.stop();
    throw error;
  }
  return {
    runtime,
    async run(input: string) {
      if (!accepting) throw new Error("Device is not accepting new work");
      runtime.heartbeat();
      try {
        return await agent.run(input);
      } finally {
        runtime.heartbeat();
      }
    },
    async stop() {
      accepting = false;
      await runtime.stop();
    },
  };
}

Route work through the returned run() for this admission check to apply. The wrapper does not serialize concurrent requests or stop a run already in progress. Add a concurrency limit and cancellation policy when your host accepts overlapping work. The host calls stop() after it stops admission and drains active work, then closes the borrowed Agent. Restart is a request to your supervisor, not an automatic replay of unfinished work.

Presets

import { customEdgePreset, edgePreset, listEdgePresets } from "@agentium/edge";

console.log(listEdgePresets());
const preset = edgePreset("pi5-8gb");
const longerTask = customEdgePreset("pi5-8gb", { watchdogTimeoutMs: 120_000 });
console.log(preset.recommendedModel, longerTask.watchdogTimeoutMs);

Preset	Suggested model	Agent output-token value	Context value	Process-memory value
`pi4-2gb`	`tinyllama:1.1b`	256	2,048	512 MB
`pi4-4gb`	`tinyllama:1.1b`	512	4,096	1,024 MB
`pi4-8gb`	`llama3.2:1b`	1,024	8,192	2,048 MB
`pi5-4gb`	`llama3.2:1b`	1,024	8,192	1,536 MB
`pi5-8gb`	`phi3:mini`	2,048	16,384	3,072 MB

These are configuration values. EdgeRuntime consumes its monitoring interval, watchdog timeout, and thermal/memory thresholds. It does not automatically apply maxTokens, contextWindow, memoryLimitMb, or disableFeatures to the Agent or operating system. Apply supported model/Agent options explicitly and use your process supervisor for process limits.

Features

Watchdog

heartbeat() updates the last-activity timestamp. If the elapsed time exceeds the preset timeout, the runtime emits watchdog-restart, increments watchdog_restarts, and invokes onWatchdogRestart when supplied. The event name reports a requested restart; no Agent replacement occurs inside the runtime. Define what a heartbeat proves. The example marks run boundaries, so a long run can legitimately exceed the timeout. Choose a suitable timeout or call heartbeat() from meaningful progress milestones. An unconditional timer can hide a stuck work loop. An idle service also needs an explicit liveness strategy if the watchdog remains enabled. Your supervisor owns cancellation/drain, Agent cleanup, process replacement, and reconciliation of any external effect whose result is unknown. See recovery.

Resource monitor

CPU thermal and memory warnings mark the runtime as degraded. When monitored CPU/memory values recover, it emits recovered. The resource monitor also reports disk and GPU warnings through runtime.getMonitor(); those are not automatic runtime restart or throttling policies.

Event	Source	Host decision
`degraded`	Runtime	Pause admission, alert, or reduce future work
`recovered`	Runtime	Resume only if other health conditions allow it
`watchdog-restart`	Runtime	Request host recovery and reconcile active work
`thermal-warning`, `memory-warning`	Runtime and monitor	Inspect the reading and threshold
`disk-warning`, `gpu-warning`	Monitor	Apply storage/GPU policy in the host
`resource-snapshot`	Runtime	Export a measurement to your monitoring system

Health endpoint

After the host starts the runtime, inspect:

curl http://127.0.0.1:9090/health

The result includes state, uptime_ms, watchdog_restarts, resources, and degraded_reason. resources contains the latest snapshot; temperature and GPU measurements can be unavailable. The built-in server returns 200 for both running and degraded, and 503 for stopped while reachable. Its status is not a readiness guarantee for your application. Implement readiness from your admission policy when a load balancer must stop sending work. The built-in endpoint has no authentication or configurable bind host; protect it with your network configuration, or set disableHealthCheck: true and expose getStatus() through your existing protected server. Monitoring timers and the health server are unreferenced; they do not keep an otherwise idle Node process alive.

Config

Option	Behavior
`preset`	Required preset ID or `EdgePreset`
`agent`	Required existing Agent; its lifecycle remains host-owned
`healthPort`	Health server port, default `9090`
`disableHealthCheck`	Skip the built-in health server, default `false`
`onWatchdogRestart`	Callback when the watchdog requests host recovery
`sheddableToolkits`	Accepted configuration, but v4 does not automatically remove tools

GPU monitoring

ResourceMonitor probes nvidia-smi. If it is unavailable or fails, gpu is absent. Reading one snapshot is enough for a one-time inspection; start() and stop() add periodic events.

import { ResourceMonitor } from "@agentium/edge";

const snapshot = new ResourceMonitor().snapshot();
if (snapshot.gpu) {
  console.log(snapshot.gpu.name);
  console.log("GPU memory GB:", snapshot.gpu.memoryUsedGb, "/", snapshot.gpu.memoryTotalGb);
  console.log("GPU utilization (%):", snapshot.gpu.utilizationPercent);
} else {
  console.log("No GPU measurement available");
}

GPU snapshot fields

Field	Meaning
`name`	Reported GPU name
`memoryUsedGb`, `memoryTotalGb`	Used and total GPU memory in GB
`utilizationPercent`	GPU utilization percentage
`temperatureC`	GPU temperature in Celsius

The monitor emits gpu-warning when GPU memory usage exceeds its memoryThreshold ratio, default 0.85. Its payload contains memory used/total and utilization; it is not a full resource snapshot.

Acting on GPU pressure

Use measurements in an explicit host admission rule. This factory starts a monitor and returns the gate and its cleanup function:

import { ResourceMonitor, type ResourceSnapshot } from "@agentium/edge";

export function watchGPUHeadroom(minimumFreeGB: number) {
  const monitor = new ResourceMonitor({ intervalMs: 10_000 });
  let accepting = false;
  monitor.on("snapshot", (snapshot: ResourceSnapshot) => {
    accepting = snapshot.gpu !== undefined &&
      snapshot.gpu.memoryTotalGb - snapshot.gpu.memoryUsedGb >= minimumFreeGB;
  });
  monitor.start();
  return {
    canAcceptWork: () => accepting,
    stop: () => monitor.stop(),
  };
}

This policy denies GPU-dependent work when no measurement is available. Choose a different fallback for CPU workloads. The host must consult the gate before submitting work; the monitor cannot intercept runs by itself. Forward selected readings to your metrics sink explicitly—resource monitoring does not automatically create an exporter or Prometheus integration.

Verify the host behavior

Test admission and supervisor callbacks with controlled events before connecting hardware. On the target device, confirm real readings, heartbeat milestones, readiness behavior, and shutdown. Continue with cloud synchronization when your receiving service is ready.

Find an integration

Voice and call adapters

Sandbox and telemetry

Providers and services

Protocols and devices

Monitor a device runtime

Quick start

Presets

Features

Watchdog

Resource monitor

Health endpoint

Config

GPU monitoring

GPU snapshot fields

Acting on GPU pressure

Verify the host behavior

​Quick start

​Presets

​Features

​Watchdog

​Resource monitor

​Health endpoint

​Config

​GPU monitoring

​GPU snapshot fields

​Acting on GPU pressure

​Verify the host behavior

Quick start

Presets

Features

Watchdog

Resource monitor

Health endpoint

Config

GPU monitoring

GPU snapshot fields

Acting on GPU pressure

Verify the host behavior