The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
core/runtime
The embeddable composition surface: CoreBuilder → CoreRuntime. This is
what openhuman-embed's Harness and the standalone openhuman-core
binary both build on to host the core without duplicating
run_server_inner.
Two-phase model
CoreBuilder::build(): initialization only. Registers controllers, loads the master key, seeds the RPC bearer, initializes the workspace-bound stores, and runs the pure-registration part ofbootstrap_core_runtime. No port is bound. Afterbuild()returns,CoreRuntime::invokecan dispatch any RPC method in-process and agent turns can run: a harness-only embedder usingServiceSet::none()needs nothing more.openhuman_rpc::server::serve(&runtime, …): transport + background services. Binds the HTTP listener (whenServiceSet::rpc_httpis set), mounts the router, fires the readiness signal, callsCoreRuntime::start_services, and serves until shutdown, then runsCoreRuntime::exit_cleanup. Whenrpc_httpis unset it just starts the selected background services and returns: the caller owns the process lifetime. The server lives inopenhuman-rpc, above this crate; a runtime that needs no transport callsstart_servicesdirectly.
CoreRuntime::invoke(method, params) dispatches an RPC method in-process
through jsonrpc::invoke_method: the same path the HTTP /rpc handler and
the CLI use, wrapped in CoreContext::scope so the ambient context resolves
correctly. openhuman_embed::Harness goes through this call, never through
domain operations directly.
ServiceSet: which background services and transports run
Each flag is independent. Presets:
| Preset | Shape |
|---|---|
ServiceSet::desktop() |
Everything on: the Tauri shell and standalone openhuman-core run. |
ServiceSet::headless_api() |
HTTP JSON-RPC only (rpc_http): no Socket.IO, cron, channels, or login-gated services; a single-core cloud/server deployment. |
ServiceSet::none() |
No transport, no background services: a library/harness embedder driving only CoreRuntime::invoke. |
ServiceSet::embedded() |
No transport (rpc_http: false), but the background work a long-lived embedded session expects: cron, login-gated services, memory queue, harness init, skill catalog refresh, memory sync. socketio/channels stay off because such a host reads state through the facade and owns its own networking. |
Individual services still honor their own runtime gates inside
runtime/services.rs regardless of ServiceSet selection: cron checks
config.cron.enabled; channels returns early on
OPENHUMAN_DISABLE_CHANNEL_LISTENERS=1 (also folded into [components].channels) or when
config.channels_config.has_listening_integrations() is false; login_gated
(spawn_login_gated_services) defers the login-gated services until a user
session exists on disk. ServiceSet picks whether a service is spawned at
all; the gate picks whether it runs for this user.
DomainSet: which domain families exist at runtime
Sibling of ServiceSet: where ServiceSet selects background services and
transports, DomainSet selects which controller/tool/store/subscriber
surfaces are live, one flag per DomainGroup (see
../all.rs's DomainGroup for the full family list and the
harness/gate/platform split). DomainSet::allows(group) is the query the
registry filters on.
| Preset | Shape |
|---|---|
DomainSet::full() |
Every family on: today's default, byte-identical to registration with no runtime narrowing. |
DomainSet::harness() |
agent + memory + threads + config + security only; every gate family and platform off. The embeddable agent core; see the lean headless example. |
DomainSet::embedded() |
The harness families plus flows (boot reconciliation keys off ctx.domains().flows), skills, channels (channel.web_chat is tagged Channels and is how an embedded host drives chat turns), inference, integrations, automation, runtimes, and platform. mcp/web3/voice/media/desktop/hosted/modules stay off: an embedded host supplies its own routing and presentation. |
DomainSet::kernel() |
The floor: threads + config + security only. Distinct from none(): this is "opt a subsystem back in from nothing," so agent and memory (the two largest, most replaceable subsystems) are deliberately off. See the capability report example for inspecting runtime composition. |
DomainSet::none() |
Every family off. |
TokenSource: how the RPC bearer is seeded
TokenSource::Fixed(Arc<String>): an in-memory bearer supplied by the embedder (the Tauri shell'sCoreProcessHandle.rpc_token), seeded viaauth::init_rpc_token_with_value; never crosses the process environment.TokenSource::EnvOrFile: the standalone fallback: readOPENHUMAN_CORE_TOKENfrom the environment if present, otherwise generate a fresh token and write{root}/core.token(0o600 on Unix).
CoreBuilder setters
CoreBuilder::new(host_kind) defaults to TokenSource::EnvOrFile,
ServiceSet::desktop(), DomainSet::full(), and ToolGroups::default()
(every group withheld behind use_skill, the desktop app's shape). The
three capability axes only narrow: a group set to Advertised whose tools
are compiled out, or whose DomainGroup is off, stays absent.
.services(ServiceSet),.domains(DomainSet),.tool_groups(ToolGroups): the three independent narrowing axes. They control which services run, which domain families exist, and how the tools of the families that do exist are disclosed (advertised on the wire, withheld behind the pack proxy, or not registered at all)..token(TokenSource),.host(impl Into<String>),.port(u16)..config(Config): supply the config outright instead of lettingbuild()discover one fromconfig.toml+ environment; used verbatim, no env overlay applied automatically..workspace(dir): sugar over.config(): rootsworkspace_diratdirand setsconfig_pathtodir/config.tomlso credentials and sessions resolve beside the workspace rather than a previous config root..action_dir(dir): sugar over.config()for the agent's read/write root..backend_url(url).
CoreContext and initialization order
runtime/context.rs's CoreContext owns the core's initialization
order: register controllers, load the master key, seed the RPC bearer,
initialize the workspace-bound stores, and run the pure-registration part of
bootstrap_core_runtime. init_stores gates each store on its owning
DomainGroup via StoreInitPlan: the memory driver binding (Memory), the
image-attachment sidecar dir (Agent), and the legacy-workflow prune
(Skills). The keyring-path log and the boot-time Sentry user bind run
unguarded for every DomainSet. The WhatsApp store moved to the Tauri
shell and the people store is owned by the bound memory driver, so neither
is seeded here. CoreContext also holds the DomainSet for its scope and,
when supplied, the embedder's Config. RPC handlers otherwise re-resolve
config independently per dispatch, so an embedder-supplied config would be
silently ignored without this seam.
The "wrong-workspace guard" (Sentry OPENHUMAN-CORE-48 / TAURI-RUST-8NM)
lives in CoreContext::init_with_config: when no config was supplied and
Config::load_or_init() fails, it logs an error and skips init_stores
entirely. Memory stays explicitly uninitialised for the run and callers get
a "memory client not ready" error, rather than the core falling back to
Config::default() and seeding stores against the wrong workspace.
CoreContext::scope(ctx, fut) establishes the ambient context for the
duration of a future (used at the try_invoke_registered_rpc chokepoint and
by CoreRuntime::invoke); CoreContext::current falls back to a
process-wide default context when no scope is active, which is what lets
existing single-tenant call sites keep working unmodified.
Operating mode: SingleUser and Saas
runtime/mode.rs holds the process mode. SingleUser is today's
behaviour and the default: the desktop app, the CLI and embedders. Saas
serves many users from one process, one profile per user, behind a trusted
gateway that authenticates them. The mode belongs to the process, not to any
user's Config. The first SaaS boot locks it (lock_mode), and from then on
CoreContext::init_with_config refuses every non-SaaS core. Code asks
is_saas(), which reads an unset slot as SingleUser.
openhuman-core run --mode saas --saas-config <file> (or
OPENHUMAN_MODE=saas, which can raise the mode but never lower it) boots
through runtime/saas.rs. So does openhuman_embed::ProfileRuntime, which
runs the same saas::build in-process without serving a port (it writes a
random service token when none exists, since no gateway presents it). Either
way the lock is one-way: once it is built, no Runtime::builder() or other
non-SaaS core can boot in that process, and neither can a second SaaS core.
saas::build:
SaasConfigis the operator's file. It setsroot,service_token_file(defaults to<root>/service.token),tool_allowlist(host tool groups, seeprofiles/README.md),[sandbox](the shell container),rpc_allowlist_extra,max_profiles_open,profile_ids,idle_evict_secs,shared_backend_api_key,custom_definitionsandrequire_user_signature(defaulttrue), and the cluster settings:storage_url(the shared backend;OPENHUMAN_STORAGE_URLwins),node_id(elseOPENHUMAN_NODE_ID, else random per process),advertise_url,lease_ttl_secs(default 30) andoperator_dir(default<root>/operator). Unknown keys are refused.runtime/boot_guard.rsrefuses the boot, listing every problem at once, when:- the host kind is not
Saas; - services or domains go beyond
ServiceSet::saas()/DomainSet::saas(); - single-user or back-door environment variables are set
(
OPENHUMAN_WORKSPACE,OPENHUMAN_DEV_CONNECT, backend tokens,OPENHUMAN_CORE_TOKEN, approval gate or sandbox switched off); tool_allowlistnames something other than a tool group, or allowlistshost_shellwithout a working Docker, with networkhost, no image, or non-positive limits;rpc_allowlist_extrais non-empty (the per-user RPC surface is fixed);- the root is relative, missing, world-writable or inside
~/.openhuman; - the service token is missing, readable by others, or shorter than 32 bytes;
- the node is clustered (
advertise_urlset) without a storage URL whose driver keeps compare-and-swap atomic across processes (SQLite, MongoDB).
- the host kind is not
- The operator plane boots with its own config under
operator_dir()(<root>/operator/by default), so it never resolves~/.openhumanor anactive_user.toml. The gateway bearer is the RPC token.
The SaaS presets are closed. DomainSet::saas() registers the operator plane
(DomainGroup::Operator, the profiles.* controllers) and the user
families whose per-user isolation has landed (threads, channels for web chat,
memory). profiles::surface
keeps the two planes apart: the operator scope reaches only the operator
plane, and a user's scope only the reviewed USER_METHODS.
saas::build installs the process's profiles::ProfileHost. Each open
profile (<root>/users/<profile-id>/, the desktop's user layout) runs under a
context derived from the operator's, with its own forced config, policy,
profile (its default agent has no session_agent, as on the desktop),
behind a lease that keeps it on one process
(see profiles/README.md). saas::build also starts the lease heartbeat.
Three guards keep SaaS work from falling back to process-wide state:
- Config redirect. In SaaS,
Config::load_or_init()returns the config the current context carries and fails outside any context (config/schema/load/saas_scope.rs). It never resolvesOPENHUMAN_WORKSPACE,active_user.tomlor~/.openhuman. - Scoped spawns.
runtime/spawn.rs'sspawn_scoped/spawn_blocking_scopedcarry the caller'sCoreContextinto the spawned task (the memory identity is explicit and is handed to spawned work as a value).scripts/ci/check-saas-ambient.mjs(pnpm saas:ambient) ratchets the bare spawns, directload_or_initcalls, environment writes andhome_dir()lookups that remain.CoreContext::propagatefollows the same rule in SaaS. - The tenant key.
runtime/tenant.rs: a context derived withContextOverlay::profile(id)serves that SaaS profile, andcurrent_tenant()readsTenant { profile, agent }from the task's own scope only (CoreContext::scoped), failing closed withNoTenantrather than falling back to the operator. Per-tenant state keys on it:tenant_key(&tenant, id)(injective; the bare id on the desktop) for in-process tables keyed by caller-chosen thread or session ids,session_key(&tenant)for the host session store, andstorage::scope_for_profilefor the storage backend. A profile gets fresh state slots,slot_forhands an unscoped SaaS task a throwaway slot, andCoreContext::tenant_in_use()reports whether turns still run on a profile, so a host never evicts it mid-turn. The ratchet'sambient-contextrule baselines theCoreContext::current()and.session_agent()reads that remain outsidecore/runtime/.
DomainSet lives in runtime/domain_set.rs and DomainGroup in
core/domain_group.rs. Both are re-exported from their old paths.
Shared tokio tuning constants
runtime/mod.rs declares two constants every multi-thread runtime that may
host an agent turn must set:
AGENT_WORKER_STACK_BYTES(20 MiB): a single agent turn is a very large async state machine (system prompt + hundreds of tool specs + the nested provider/tool loop), and delegating to a sub-agent nests another one. That overflows tokio's default 2 MiB worker stack and aborts the process.MAX_BLOCKING_THREADS(64): tokio defaults this to 512, which combined with the raised stack size could reserve up to64 × 20 MiBof virtual stack space. Physical pages are committed as a thread's stack grows.spawn_blockingon these runtimes backs SQLite, filesystem grep/glob, document parsing, and URL guarding: bounded, bursty concurrency, so 64 leaves headroom while capping the idle footprint.
Related docs
- ../README.md: the rest of
core/, covering dispatch, registry, event bus, transport, and CLI. - Embedding OpenHuman
- Deep architecture reference