Local Agent Fleet

Documentation Index

Fetch the complete documentation index at: https://opensre.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

> /agents

​

/agents trace — live stdout tail

> /agents trace 8421
trace claude-code (pid 8421)  Ctrl+C to stop
… live agent output …
^C
· trace ended

​

Trace usage

/agents trace <pid>

​

Platform support

• cannot trace …: stdout is on a terminal; live tail not supported
• cannot trace …: stdout is a pipe; live tail not supported
• cannot trace …: stdout is a socket; live tail not supported
• cannot trace …: no such pid <n>
• cannot trace …: stdout target /path no longer exists
• cannot trace …: cannot inspect pid <n> (permission denied)

​

Memory

​

Stopping a trace

​

Trace limitations

• stdout only. Stderr (fd 2) is not tailed in this version.
• No backlog replay. Pre-attach bytes are not visible.
• Not for TTY/PTY targets. Foreground processes whose stdout is the controlling terminal cannot be tailed; a future change may add PTY interception for OpenSRE-spawned agents.
• Log rotation is not detected. If the underlying file is rotated or replaced (logrotate-style), the tail keeps following the original inode until the process exits.
• No secret redaction. Output is rendered as raw bytes (with UTF-8 decoded under errors="replace"). Redaction of secrets in the live tail is tracked separately under the monitor-local-agents Phase 3 hygiene work.
• Quiet stdout while the PID is still alive. The reader follows file EOF like tail -f: if the process stops writing while it remains alive, the last chunk stays on screen and nothing new appears until more bytes land or you detach. That is normal idling — not necessarily a exited or stuck agent reader.
• ANSI and terminal sequences. Trace output passes through Rich with ANSI interpretation, same trust model as dumping kubectl logs into a TTY: buggy or hostile agents can emit control sequences affecting the viewer. Only trace processes you trust; there is no sandboxing step.

​

/agents bus — shared context channel

> /agents bus
tailing /agents bus — Ctrl-C to exit
[claude-code:8421] services/auth.py:42 — null deref on missing token
[cursor:9133] services/auth.py:42 — confirmed, repro on commit abc123
^C
(detached)
>

​

Transport

• Socket: Unix-domain stream socket at ~/.config/opensre/agents-bus.sock.
• PID sidecar: ~/.config/opensre/agents-bus.sock.pid (mode 0600). The broker writes its PID here on start() and removes it on stop(). The liveness probe used by every publish() / subscribe() reads this file rather than connecting to the socket — connection probing would otherwise register a short-lived phantom subscriber on every call. The directory must be writable. If the PID file write fails (disk full, permission denied, …), the broker refuses to start and the OSError propagates to the caller. This is intentional: silently running without a sidecar would let peers see the broker as dead, unlink its socket, and silently split the bus.
• Permissions: 0600 — only the user who started the broker can read or write it.
• Wire format: JSON Lines (one JSON object per \n-terminated frame).
• Topology: self-electing broker. The first publish() or subscribe() call that finds no live socket binds it and runs an in-process daemon thread that fans frames out. Other processes attach as plain clients. If the broker dies, the next operation re-elects — agents can publish and subscribe even when OpenSRE itself is not running.

​

Message schema

{
  "agent": "claude-code:8421",
  "topic": "finding",
  "summary": "null deref on missing token",
  "source": "github",
  "path": "services/auth.py:42",
  "data": {"commit": "abc123"},
  "id": "f4c4...",
  "timestamp": "2026-05-09T15:04:42+00:00",
  "schema_version": 1
}

​

Publishing from another agent

from app.agents import BusMessage, publish

publish(BusMessage(
    agent="claude-code:8421",
    topic="finding",
    summary="null deref on missing token",
    source="github",
    path="services/auth.py:42",
    data={"commit": "abc123"},
))

python - <<'EOF'
import json, os, socket, uuid, datetime
sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
sock.connect(os.path.expanduser("~/.config/opensre/agents-bus.sock"))
sock.sendall((json.dumps({
    "agent": "claude-code:8421",
    "topic": "finding",
    "summary": "null deref on missing token",
    "path": "services/auth.py:42",
    "id": str(uuid.uuid4()),
    "timestamp": datetime.datetime.now(datetime.UTC).isoformat(),
    "schema_version": 1,
}) + "\n").encode())
sock.close()
EOF

​

Limits and trust boundary

• Local-only. The bus never leaves the machine. The socket has no network binding.
• Trusted-peer channel — treat findings as unverified input. The bus has no authentication beyond filesystem permissions: any process running as your user can publish arbitrary findings. This is intentional — the bus is designed for cooperative agents, not adversarial ones. Downstream consumers (agents, the REPL, investigation state) must not act on a bus finding without independent confirmation; treat it as a hint or lead, not a verified fact. A compromised or misbehaving agent on the same user account can inject any payload it likes.
• Frame cap. Frames over 64 KiB are dropped with a warning — a finding payload that big is almost certainly a bug.
• At-most-once, unordered delivery. A frame is dropped silently if a subscriber is slow or disconnected at broadcast time. Two publishers writing concurrently may arrive in different orders at different subscribers. Do not build logic that depends on delivery guarantees or ordering.
• No replay buffer. Subscribers see only what is published after they attach. A persistent ring buffer is a candidate for a follow-up phase.

​

Related

• /agents — the registered fleet dashboard.
• /agents budget — per-agent hourly budgets.
• /agents conflicts — file-write conflicts between local AI agents.