Limits and budgets
Every limit that can end a Probe MCP request, in one place. Most only bite when you ask Claude for something broad — “search every log message this week”, “walk every switch” — which is exactly the case worth knowing about in advance.
If a call came back empty or with an error and you want to know why, start with services that ship disabled: a function that exists but was never enabled on the probe is the most common surprise.
The code_mode run
Section titled “The code_mode run”| Limit | Value | What happens when you hit it |
|---|---|---|
| Wall-clock budget | 30 seconds | The run returns { error: 'timeout' }. Work already done is lost |
| Tunnel round-trip | 10 seconds per on-demand call | That one call resolves with an error; the rest of the program keeps running |
Each code_mode invocation gets a fresh 30-second budget — the limit is
per-run, not per-conversation, so a follow-up question starts over.
The two timeouts compose badly on purpose: three slow on-demand calls in
sequence can spend the whole 30-second budget by themselves. Stored functions
(list_probes, syslog_rollups, snmp_metrics, top_talkers, list_devices,
probe_status) don’t cross the tunnel and are far cheaper — see stored vs.
on-demand.
Services that ship disabled
Section titled “Services that ship disabled”Several probe.* functions depend on a probe service that is off by default.
The function is always present in code mode; it fails at the probe with a
specific error until you enable it in
/etc/probe-mcp/probe.yaml.
| Functions | Needs | Default | Error until enabled |
|---|---|---|---|
top_conns, search_conns, pcap_query | pcap.enabled (plus CAP_NET_RAW) | Off | pcap disabled |
device_cli, ssh_send, ssh_read, ssh_close, run_device_cli | ssh.enabled | Off | ssh proxy disabled |
https_forward | reach_through.enabled | Off | reach_through disabled |
serve_tftp, stop_tftp | tftp.enabled | Off | tftp disabled |
query_flows | flow_collector.enabled | Off | flow collector not enabled |
Syslog, SNMP polling, SNMP traps, discovery, the vault, and the rollup engine are all on by default and need no configuration.
top_talkers is the exception to the pattern above. It’s a stored function
reading aggregates the engine already holds, so with the flow collector off it
returns an empty list rather than an error — there was never any sFlow to
aggregate. An empty top_talkers and a failing query_flows have the same
cause.
Per-function caps
Section titled “Per-function caps”Row limits
Section titled “Row limits”Every list-shaped function accepts a limit, and each has its own ceiling. Ask
for more and the argument is rejected rather than silently truncated.
| Function | Default rows | Maximum |
|---|---|---|
query_syslog, search_syslog, query_flows | 100 | 1,000 |
list_devices, search_conns, auth_sessions | 100 | 500 |
top_conns | 50 | 500 |
inventory | all | 2,000 |
reconcile_inventory | — | 5,000 devices in the controller list you pass it |
generate_scorecard | — | 50 findings per report |
top_talkers | 20 — fixed | not adjustable |
Windows and sizes
Section titled “Windows and sizes”| Function | Limit | Value |
|---|---|---|
topology | Wireless association look-back (withinHours) | default 24 h, max 720 h (30 days) |
inventory, reconcile_inventory | ”Seen alive within” (aliveWithinSecs) | default 300 s, max 86,400 s |
pcap_query | Packets per slice | default and max 50,000, capped at 64 MiB |
pcap_query | Time window | defaults to the last 5 minutes |
https_forward, connection_egress | Upstream timeout (timeoutMs) | caller-set, capped at 9 s |
https_forward | Response body | probe-side cap of 8 MiB (reach_through.max_bytes) |
connection_egress | Response body | 8 MiB |
serve_tftp | Serve window (ttlSec) | clamped to the probe’s tftp.ttl_sec — 300 s by default; ttlSec above 900 is rejected outright |
serve_tftp | Config file size | 1,024 KB (tftp.max_kb) |
device_cli | Terminal geometry | up to 500 columns × 300 rows |
ssh_read | Wait for new output (waitMs) | default 1,000 ms, max 8,000 ms |
run_device_cli | Commands per batch | 8 |
run_device_cli | Output captured | 256 KB |
The 9-second upstream cap and the 10-second tunnel round-trip are deliberately close: a reach-through call that needs longer than 9 seconds would outlive the tunnel call carrying it.
Concurrency and storage on the probe
Section titled “Concurrency and storage on the probe”| Resource | Limit | Config key |
|---|---|---|
| Concurrent SSH sessions | 5 | ssh.max_sessions |
| SSH idle timeout | 600 s, then the session is reaped | ssh.idle_timeout_sec |
| TFTP serves | one file, one client at a time — a second serve_tftp returns serve_failed until you stop_tftp | — |
| TFTP serve window | default and ceiling are the same key — asking for longer than tftp.ttl_sec silently gets you tftp.ttl_sec | tftp.ttl_sec |
| Vault entries | 128 | vault.max_entries |
| Packet-capture ring buffer | 1 GiB, oldest packets overwritten | pcap.ring_bytes |
| Offline upload buffer | 256 MB | buffer.max_size_mb |
An SSH session that goes idle for ten minutes is closed underneath you — a later
ssh_send returns session_not_found. Open a new session rather than treating
it as an error.
How long data is kept
Section titled “How long data is kept”Retention is enforced on the probe, not in the cloud. Once a window has aged out, no query can recover it.
| Data | Kept for | Also capped at |
|---|---|---|
| Syslog and SNMP-trap events | 168 hours (7 days) | 1 GiB |
| Flow aggregates | 24 hours | — |
| Individual flow records | 6 hours | 500 MB |
| Packet capture | until the ring buffer wraps | 1 GiB |
Whichever limit is reached first wins — a chatty network hits the 1 GiB event cap well before seven days. Aggregates shipped to the engine (syslog rollups, SNMP health, top talkers) are the part that survives, which is why those queries still answer questions about last week when a raw search can’t.
How fast a dead probe is noticed
Section titled “How fast a dead probe is noticed”A probe showing Online in the dashboard is not proof it is reachable right now, and the gap is large enough to confuse a live call.
| Event | Timing |
|---|---|
| Probe heartbeat | every 60 seconds |
| Silence before a probe counts as offline | 180 seconds (three missed heartbeats) |
| Sweep that flips the status | every 5 minutes |
So a probe that dies can keep showing Online for up to roughly eight minutes.
During that window an on-demand call doesn’t return probe_offline — it returns
probe_unreachable, which means the tunnel has no healthy origin. Both mean
the same thing for you: the probe isn’t answering. See
Troubleshooting.