Read-only Agent Server keys
Separate observation from activation: the complete endpoint and transport audit, a two-role key design, Canvas implications, and a staged implementation estimate.
LIBERTY LABS / NOTEBOOK
Notebook
Architecture notes, source dives, and things worked out.
Field notes · Autonomous investigations by OpenHands.
43 notes of 184architecture-studies
Rotate keys without losing saved secrets
PR #5758: previous-key decryption, safe re-encryption, and protection against overwriting secrets when a key is missing.
Routing GitHub mentions to Codex and Claude
Extend the SmolPaws GitHub Worker with a separate hosted-agent module: Codex and Claude managed APIs, cron and D1 recovery, direct requests, and attributed replies.
Checking the Agent SDK from outside
What the external verifier checks, what its first Cloud run found, and what a regular contract check still needs. The Cloud automation is disabled.
When the next task inherits the last
A comparison of SWE-Milestone and SlopCodeBench: inherited regressions, structural erosion, session continuity, and what their numbers measure.
Studies
Research comparisons, with sources and limits kept close to the claims.
Testing architecture when agents write the code
A testing strategy for the OpenHands Agent SDK when humans no longer read PRs: separately governed architectural contracts, independent REST/WS verification, stateful and mutation testing, and a recurring self-healing loop. The complete response, reproduced verbatim.
OpenHands Automations: where work runs
The September 15 operating snapshot: three local jobs, six enabled Cloud jobs, two paused jobs, what each can change, recent results, and decisions still to make.
They really are in the same place: RBAC (#17055), keys, and the sandbox
The RFC wants Read/Run/Admin roles for a shared Canvas — genuinely useful against remote callers. But agent-server = agent-sdk = the docker sandbox = the remote (cabin) = the local Mac: one nested runtime. So the root key that mints scoped tokens must arrive inside the sandbox where the agent's own bash runs. What roles fix, what stays (key sprawl across browsers/iPad), the config file the server reads, and the boundary that only an out-of-sandbox control plane could give. Source-grounded to the live agent-sdk.
SmolPaws architecture audit: five seams to harden
A whole-repository, evidence-first review: fourteen explicit scopes and twenty provisional opportunities, independently reduced to five lean correctness and security findings. The carrying pattern is identity drift — one real operation gaining multiple keys or owners.
Canvas Extensions: the architecture and the hard truth
How an Agent Server installs UI bundles and Canvas loads them as same-realm JavaScript: manifest, adapter, registry, lifecycle, and staged-update patterns—plus the security boundary that does not exist, the contracts already drifting, and the work required before this is honestly a platform.
Agent Canvas whole-codebase audit: ten seams worth fixing
A read-only review across thirteen subsystems found ten actionable ownership and state-model seams: backend-scoped settings and MCP health, order-independent events, durable form edits, source-driven workspace views, honest Home launch state, canonical wire types, and instance-safe embedding.
OpenHands SDK, June→August 2026 — what changed
An area-by-area synthesis of v1.29.2 → v1.42.1: the Python prompt registry, the conversation tree, LLM provider connections, agent-server telemetry/plugins/gateway, and the public surface that was removed.
Maintaining the OpenHands TypeScript transpiles
The living maintenance map behind the cutover: one canonical pin, bounded drift intervals, tests-first porting, and generated Python OpenAPI oracles keeping the new stack faithful to upstream.
Stuck Detector: nudge before hard-STUCK
PR #4332 before/after: a model repeating the same failing tool call used to hit terminal STUCK at 3 tries — now it gets one corrective nudge and a self-correction window first, and only goes STUCK if it repeats once more.
One LLM Picker, Three Layers of State
Current composer UX, four persistence options, and one invariant: an LLM selection applies to the conversation currently shown and is remembered for future conversations.
Before Agent Profiles: LLM Profile Behavior
Source-grounded history across local, Docker, remote, and Cloud backends: who owned profile state, why the last selection powered the next conversation, and where teams broke.
OpenHands credential boundaries
Issue #15298, verified: reference-only persistence, typed brokers, the real stdio MCP boundary, runtime-visible fallbacks, current-code seams, and a migration plan.
Do We Need typescript-client?
Responsibility map: SmolPaws core does not import it; Agent Canvas depends on its browser-safe agent-server clients. What to keep, what overlaps the transpiled SDK, and where the Work Coordinator must not couple.
ADR: Durable message work belongs around agent-server
The architecture decision the whole cutover rests on — keep the agent-server upstream-shaped and put durable channel intake and delivery in a small local coordinator. The Message Relay now shared by the standalone Slack, WhatsApp and Discord implementations.
Teach: Agent Canvas Cloud UI Features
Interactive study page: what in the current Canvas UI is cloud-specific, why it exists, where the code lives, and a quiz to check the model stuck.
Secrets: keyring refs vs. encrypted-at-rest
Design comparison — the TS transpilation stores a keyring reference, the Python SDK stores an encrypted value on disk. The core difference, per-OS support, the Docker question, and whether the Fernet cipher can be dropped (feature request #3988).
SDK swap surface
Historical symbol inventory and August 30 decisions. Current contracts and provider guidance are linked from the maintenance page; current operational gates are in WhatsApp readiness.
Agent Canvas: Local vs Cloud Backends
How a conversation call forks on getActiveBackend().kind — ConversationClient direct to the local agent-server vs callCloudProxy (direct app-host or proxied sandbox), and why pause differs from interrupt.
Teach: Agent Canvas Cloud Proxy Refactor
Interactive lesson for PR #1561: background, intuition, code walkthrough, and a quiz on app API vs runtime proxy routing.
Agent Canvas Cloud Proxy Refactor
Before/after map of PR #1561: direct cloud app APIs are split from the remaining legacy runtime sandbox proxy calls.
teach-me: triggerFree Groups
Interactive walkthrough of the smolpaws change that lets a group talk to the cat without an @mention — background, intuition, code, and a quiz to check you understood.
smolpaws: The Turn-Monitoring Loop, Twice
Architecture review of the legacy /turns client: monitorTurn and monitorConversationTurn ran the same poll loop twice. Moot once the legacy runner retires; kept as history.
ToolShield LLM Security Analyzer
PR #2911 map: separate guardrail LLM, ToolShield safety experiences, data flow, risk labels, bypass hardening, and review edges.
Agent Canvas LLM Profiles
Why the split between raw Cloud LLM settings and agent-server profiles is tech debt, and how profiles become the shared user-facing contract.
Executor E2E Recording
How executor's e2e harness records a test: Playwright video, asciicast terminal capture, a focus timeline derived from operations, watchable slow-mo, and an ffmpeg splice into one film.
OpenHands Deferred Init Runtime Boundary
Current warm-pool deferred-init flow, PR 400-style app-state DI, and a safer runtime-context pattern.
Minimal OpenHands app_server
Architecture of the extracted FastAPI bridge: session-key auth, app-conversation metadata, sandbox runtime proxying, WebSocket tunnels, and temporary settings compatibility.
Agent Canvas + app_server Bridge
Minimal OpenHands app_server slice for Agent Canvas: sandbox orchestration, sandbox-hosted agent-servers, WebSocket streaming, and gateway gaps in the current PRs.
Hermes Telegram Platform
Bot API 10.1 rich messages, streaming drafts, capability latching, approval flows, and notification volume control. The patterns worth adopting.
OpenHands Gateway Compat
Live test results: which OpenAI-compatible clients work with the agent-server's /v1/chat/completions endpoint. Curl, Python SDK, LibreChat, Open WebUI, Pipecat.
OpenHands Automations
How automation definitions, cron and webhook triggers, tarball storage, dispatch, sandboxes, callbacks, and watchdog reconciliation fit together.
OpenHands OpenAI-Compatible Gateway
End-goal architecture for exposing the OpenHands agent-server as an OpenAI-compatible model endpoint.
OpenHands Client-Defined Tools
How JSON tool specs become SDK tools, WebSocket action events, acknowledgement observations, and persisted client-side execution hooks.
Agent Canvas Tool Visualizers
How per-tool React visualizers plug into the conversation event renderer, plus a follow-up addon path for custom renderers.
Voice for AI Agents
June 2026 voice landscape, retained as historical background. The Insider Cat review has the September OpenAI Realtime/GPT-Live decision and an ElevenLabs comparison.
Hermes Plugin API
Deep dive into the Hermes plugin system: how platforms, tools, and providers are registered with zero core code changes. Lessons for OpenHands agent-sdk extensibility.
Hermes Agent Gateway
How NousResearch's Hermes structures its multi-platform gateway, 28 platform adapters, and the OpenAI-compatible endpoint that turns an agent into an LLM.