The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
platform
Services about the core process itself rather than about what the agent is
doing: is it running, is it healthy, what did it cost, is it connected to the
backend, does it need an update, how does it restart. The desktop shell, the
CLI, and the frontend reach these through ordinary JSON-RPC controllers, and
the boot path in core/runtime/ starts the background pieces.
Nothing here is feature-gated. A build whose only inference driver is an
external backend still has to start, stay healthy, report cost, and be
reachable, so this family ships in every build. Its controllers are tagged
DomainGroup::Platform, the catch-all group that DomainSet::platform
switches at runtime.
How it works
Most members are small request and response domains. A few take part in startup, and two are driven by events rather than calls. In boot order:
core/runtime/bootstrap.rs
|- platform::cost::init_global(cfg.cost, workspace) cost ledger singleton
|- platform::socket::set_global_socket_manager(..) SocketManager singleton
core/runtime/subscribers.rs
|- platform::health::bus::register_health_subscriber()
|- platform::service::bus::register_restart_subscriber()
|- platform::service::bus::register_shutdown_subscriber()
core/runtime/services.rs
|- platform::update::scheduler::run(config.update) periodic update check
|- spawn_socket_auto_connect(..) if socketio service on
token_provider_from_config(config) and a transport is
installed
core/all.rs
'- about_app, health, doctor, cost, connectivity,
service, socket, update controllers (DomainGroup::Platform)
The event-driven pieces:
healthkeeps an in-memory component registry. Its subscriber listens tosystemandchanneldomain events and marks components ok or in error.GET /healthon the RPC server reads the verdict: 503 only when a critical component (core) is unhealthy, 200 with adegradedflag otherwise.serviceturns a restart or shutdown request intoDomainEvent::SystemRestartRequestedorSystemShutdownRequested. Its subscribers respawn the process or exit after a short flush window.updateuses the same restart path after staging a new binary.socketgoes the other way. It is the core's own Socket.IO client to the hosted backend, and it republishes inbound server events onto the bus (WebhookIncomingRequest,ComposioTriggerReceived,ChannelInboundMessage, device tunnel events) for other domains to handle.
The top-level doctor domain reads the daemon state file
service writes and the memory engine status from memory. connectivity reads the SocketManager state to tell
the frontend which of its connection channels is broken.
Layout
| Path | What it does |
|---|---|
about_app/ |
The user-facing capability catalog: what each feature does, where it is in the UI, its maturity, and its privacy disclosure. A compile-time static table with list, lookup, and search. Update it when user-visible capabilities change. |
connectivity/ |
connectivity_diag (backend socket state, loop liveness, core PID and port, a loopback port probe) and the listen-port picker the core uses to bind its HTTP listener, including stale-listener takeover and the Windows excluded-port fallback. |
cost/ |
Token usage and USD cost: an append-only costs.jsonl ledger, day and month aggregates, the 7-day dashboard, the static pricing and context-window catalog (catalog.rs), and managed vs BYOK route classification (route.rs). |
health/ |
The in-process component health registry, the HealthVerdict behind GET /health, and static system info. |
proc_metrics/ |
Cross-platform RSS and peak-RSS sampling for this process and its tree. Used by the rss-bench and library-profile bins in openhuman-benchmarks (profile/). No RPC. |
service/ |
Installs the core as a per-user OS service (LaunchAgent, systemd user unit, Windows scheduled task), self-restart and graceful shutdown over the bus, daemon-host tray preferences, and a file-backed mock for E2E (OPENHUMAN_SERVICE_MOCK). |
socket/ |
The persistent Socket.IO client to the backend: hand-rolled Engine.IO and Socket.IO handshakes over a WebSocket, reconnect with backoff, a token provider re-read on every reconnect, redirect following, and inbound event dispatch. |
startup/ |
One-shot workspace migrations run during boot (session layout, welcome-agent artifacts). Errors are logged and never abort startup. |
update/ |
Self-update from GitHub Releases: check, download and atomically stage the platform binary, then restart (SelfReplace) or leave it for a supervisor. Plus the periodic background checker. |
Key types and entry points
There is no type shared across the family. The ones contributors touch most:
HealthSnapshot,mark_component_ok,mark_component_error(health/) for reporting component state.CostTrackerandcost::init_global/try_global/rebind_global(cost/global.rs). The tracker is bound to one workspace, and signing in or out rebinds it so usage lands in the right user's ledger.SocketManagerandtoken_provider_from_config(socket/).pick_listen_port_for_hostand its variants (connectivity/), used by the RPC host when binding.ServiceStatusand the restart and shutdown publishers (service/).
RPC / CLI surface
Method names are openhuman.<namespace>_<function>.
| Namespace | Functions |
|---|---|
about_app |
list, lookup, search |
connectivity |
diag |
cost |
get_dashboard, get_daily_history, get_summary, get_usage_log |
health |
snapshot, system_info |
service |
install, start, stop, status, uninstall, restart, shutdown, daemon_host_get, daemon_host_set |
socket |
connect, connect_with_session, disconnect, emit, state |
update |
version, check, apply, run |
Agent tools from this family (registered in tools/ops.rs):
health_snapshot, health_system_info,
cost_get_dashboard, cost_get_daily_history, cost_get_summary,
service_restart, service_shutdown, and daemon_host_prefs_set. The
lifecycle mutators ship off by default through the user tool filter.
Boundaries
- The JSON-RPC server,
/healthroute, and Socket.IO server the frontend connects to belong tocrates/openhuman-rpc.platform::socketis the core's outbound client to the backend, not that server. - The backend URL belongs to the host crate that registers the config enricher
(
crates/openhuman-tinyhumans).socketreadsConfig.resolved_endpoints; with none resolved it does not auto-connect. - The session credential belongs to the host's session owner.
socketreads whatever token the core was given throughauth.set_credential. - How the desktop shell supervises the core belongs to
crates/openhuman-app/src/core_process.rs.
Gotchas
updatemutations are fail-closed behindconfig.update.rpc_mutations_enabled, and download URLs and asset names are validated at the RPC boundary.- Cost history is recorded even when
cost.enabledis off (record_usage_unconditional), and the local limits apply only to records classified as managed. BYOK and local calls are recorded but never gated. socketreportsReconnectingbetween attempts andDisconnectedonly when the loop is not running. The frontend's connectivity chip depends on that distinction.
Tests
Each member keeps sibling *_tests.rs files. The service mock backend makes
lifecycle tests deterministic.
cargo test -p openhuman platform::
pnpm debug rust platform::