The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
runtime
The first step of the two-step library API: initialize one Runtime per
process, then put any number of independently configured agents on it with
Runtime::agent. This folder owns the builder that boots the embedded core,
the Runtime handle, and the guard that tears the core down when the last
handle goes away. See
docs/gitbooks/en/developing/embedding.md
for the walkthrough and
docs/gitbooks/en/developing/performance.md
for what many agents on one runtime cost in memory.
How it works
RuntimeBuilder::new() starts from safe defaults: an ephemeral workspace,
Provider::inherit(), Access::supervised(), HostKind::Library, only the
no background services by default, and DomainSet::embedded() plus mcp and
skills when those features are compiled in. build() then runs these steps
in order:
RuntimeBuilder::build
|
|- claim RUNTIME_LIVE (AtomicBool) -> AlreadyRunning if already set
|- refuse a blank API key, or Stateless without a session store
|- install the host memory engine, if given
|- ResolvedWorkspace::resolve temp dir / Dir / scratch / Inherit
|- base Config: Inherit loads the operator's; otherwise supplied or
| default, with workspace_dir, action_dir and config_path overridden
|- backend_url, Access::apply, provider model
|- store the API key beside config_path (before boot: the scheduler
| gate reads the credential store once)
|- effective_host_kind Library on an inherited install without
| a host credential becomes Cli
|- install the session store provider (before boot: recovery runs)
|- CoreBuilder::new(host_kind).domains.tool_groups.services
| .token(EnvOrFile).config(..).build()
|- store the Session through auth, if given
v
Runtime { guard: Arc<CoreGuard>, base_config, domains, tool_groups, ... }
Any failure after the slot is claimed releases it again, so a failed build does not poison the process against a retry. The builder never mutates the process environment.
The resulting Runtime keeps the base Config every agent starts from, the
registered DomainSet and ToolGroups (agents may only narrow them), the
default Provider and Access, and a registry of live agents keyed by id
(held as Weak references, so an id frees up when its last clone drops).
CoreGuard holds the Core, the resolved workspace (and its TempDir for
an ephemeral one), and the installed session store. Both Runtime and every
AgentInner hold an Arc<CoreGuard>, so the core stays alive while any
agent or in-flight turn exists, even after the host drops its Runtime. When
the last owner drops, the guard drops the core while the process slot is
still claimed, restores the previous session store if it still owns the
slot, drops its handle on an ephemeral workspace, and releases RUNTIME_LIVE.
The ephemeral root (EphemeralRoot) is removed with a short retry loop
(background writers can recreate subdirectories just after a turn returns)
when its last holder drops. A dropped agent's deferred MCP cleanup retains the
CoreGuard and ephemeral root while it retries the close, keeping process
admission reserved until cleanup completes. If those bounded retries fail, the
workspace is preserved for an explicit retry from a live runtime or manual
reclamation after the runtime is gone; retained cleanup metadata does not keep
the runtime guard alive.
Layout
| File | What it does |
|---|---|
mod.rs |
Runtime, RuntimeError, CoreGuard and the RUNTIME_LIVE process slot. |
builder.rs |
RuntimeBuilder, its knobs and ConfigSource (Resolved: embed hands the core a config; Discovered: the core loads the operator's install, as desktop/CLI/TUI do). |
build.rs |
RuntimeBuilder::build: validation, config resolution, seam install, CoreBuilder boot; apply_provider, effective_host_kind. |
presets.rs |
Host presets library/desktop/cli/tui and the library defaults default_domains, default_services. |
seams.rs |
Process-global seams as builder options (controller_extension, tool_ranker, post_turn_hook, tool_hook, server_launcher, live_policy) and the guard that restores the restorable ones on drop. |
run.rs |
RuntimeBuilder::run_from_args / run_from_args: install the builder's process-global pieces for the process, then run the core's CLI dispatcher. |
api_key.rs |
ApiKey, a newtype over the TinyHumans key whose Debug does not print it. |
Key types and entry points
RuntimeBuilder(builder.rs):workspace,workspace_dir,action_dir,config_source,api_key,backend_url,memory_engine,session_store,provider,access,services,domains,tool_groups,host_kind,token,listen(listen_host,listen_port),session,config, the seam options (seams.rs), thenbuildorrun_from_args. Presets (presets.rs):library()(=new()),desktop(),cli(),tui().Runtime(mod.rs):agent(spec)builds an agent;agent_ids()lists the live ones;core()returns the narrowHarnessCore(config, auth);memory(root)returns one tenant'smemory::Memory;root_dir()andworkspace_dir()give paths;domains(),tool_groups()andservices()report what was registered;has_api_key()reads the credential store live, so it reflectsAuth::store_api_keyandAuth::clear_api_keycalls made after build;runtime_id()is an opaque per-instance id.RuntimeError(mod.rs):AlreadyRunning,BlankApiKey,NoSessionStore,Build(the core failed to boot),Workspace(an I/O failure),Invalid, andCall(storing a session failed).
What is runtime-wide versus per-agent
The runtime owns everything process-scoped in the core: the event bus, the
keyring and credential store, the RPC bearer, the background ServiceSet,
the registered DomainSet, and the API key. An agent owns everything the
core reads through its own context: its Config (provider route and model,
MCP servers, autonomy tier, action_dir), its AgentDefinition (system
prompt, tool scope, sandbox mode), its skills root, its narrowed
DomainSet and ToolGroups, its approval settings and parked approvals,
its sub-agents, its MCP host, its cron jobs and its per-turn state. The
crate README's "Still process-owned" list names what agents share, and its
"Lifecycle" section covers max_agents and Runtime::remove_agent.
Boundaries
- Booting the core (
CoreBuilder,CoreContext, service startup) belongs toopenhuman_core::core::runtime. See its README. - No backend transport is installed here.
openhuman-tinyhumans'sRuntimeBuilder(crates/openhuman-tinyhumans/src/runtime.rs) wraps this builder and installs the SDK transport onbuild(); seedocs/gitbooks/en/developing/tinyhumans-api-key.md. - The session store port (
SessionStoreProvider) is defined byvendor/tinyagentsand the core'sstorage::sessions; the classic on-disk provider lives inopenhuman-rpc'ssession_store.
Gotchas
- One runtime per process.
CoreContext::initseeds the process-scoped state once, sobuildreturnsRuntimeError::AlreadyRunningrather than letting two runtimes share a keyring and event bus while each believes it owns a separate workspace. Agents are the unit of multiplicity. - The tokio runtime is the host's job. Build it with
AGENT_WORKER_STACK_BYTESandMAX_BLOCKING_THREADS(openhuman_core::core::runtime) or a turn with a nested sub-agent overflows the default 2 MiB worker stack. - The provider's route is never written into the config; only its model is
(
apply_provider). Config routes persist, and a library caller must not repoint the operator's install. memory_engineandsession_storeare process-wide, like the runtime. The session store is removed with the runtime.
Tests
builder_tests.rs and api_key_tests.rs sit beside their modules. The
end-to-end suites in ../../tests/ build real
runtimes.
cargo test -p openhuman-embed --features inference,mcp,skills runtime::
Further reading
docs/gitbooks/en/developing/embedding.md: embedding the core in another product.docs/gitbooks/en/developing/tinyhumans-api-key.md: running on a TinyHumans API key.crates/openhuman-embed/README.md: the openhuman-embed crate README.