The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
Rust agent-orchestrationai-agentsai-assistantdesktopllmlocal-firstmcppersonal-aiprivacyrustsecond-braintauri
//! `CoreBuilder` → `CoreRuntime`: the embeddable composition surface.
//!
//! This is the first-class library API for hosting the OpenHuman core. It
//! splits the monolithic `run_server_inner` into two phases:
//!
//! 1. [`CoreBuilder::build`] — *initialization only*: register controllers, load
//! the master key, seed the RPC bearer, initialize workspace-bound stores,
//! and run the pure-registration part of [`bootstrap_core_runtime`]. No port
//! is bound and `ServiceSet::none` / `ServiceSet::headless_api` start no
//! background loops. After `build`, [`CoreRuntime::invoke`] can dispatch any
//! RPC method in-process, and agent turns can run — so a harness-only embedder
//! (`ServiceSet::none`) needs nothing more.
//! 2. *Transport + background services*: `openhuman_rpc::server::serve` binds
//! the HTTP listener, mounts the router, fires the readiness signal, calls
//! [`CoreRuntime::start_services`], and serves until shutdown. A runtime
//! with no transport calls `start_services` itself.
//!
//! The host boot in `openhuman-rpc` (`host::{cli, desktop}`) and its
//! `run_server*` entry points build on this builder, so the desktop shell, the
//! standalone CLI, and any new embedder share one path.
//! See the pluggable-core work (`core::runtime`) for how this fits with
//! [`context`](crate::core::runtime::context) and `services`.
use std::sync::Arc;
use crate::config::Config;
use crate::core::runtime::context::CoreContext;
use crate::core::types::HostKind;
pub use super::components::ComponentSet;
pub use super::domain_set::DomainSet;
/// Selects which background services and transports a [`CoreRuntime`] runs.
///
/// Each flag is independent. Presets cover the common hosts:
/// [`ServiceSet::desktop`] (everything — the Tauri shell / standalone CLI),
/// [`ServiceSet::headless_api`] (HTTP JSON-RPC only — single-core cloud), and
/// [`ServiceSet::none`] (no transport, no background work — library / harness).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ServiceSet {
/// Bind the axum HTTP server and serve `POST /rpc` (+ the other core routes).
pub rpc_http: bool,
/// Mount the Socket.IO realtime layer on the HTTP server (requires `rpc_http`).
pub socketio: bool,
/// Spawn the cron scheduler (still gated at runtime by `config.cron.enabled`).
pub cron: bool,
/// Spawn realtime channel listeners (Telegram, Discord, …).
pub channels: bool,
/// Spawn login-gated services (local AI, voice, autocomplete).
pub login_gated: bool,
/// Spawn the periodic self-update checker.
pub update_scheduler: bool,
/// Start memory queue workers during runtime bootstrap.
pub memory_queue: bool,
/// Refresh the skill catalog during runtime bootstrap.
pub skill_catalog_refresh: bool,
/// Boot installed MCP servers and supervise reconnects during runtime bootstrap.
pub mcp_boot: bool,
/// Composio integration sync: periodic connection sync + one-shot memory-source reconcile.
pub integrations: bool,
/// Workspace memory-source periodic sync — repos, folders, RSS, web pages.
pub memory_sync: bool,
}
impl ServiceSet {
/// Everything on — the desktop shell and the standalone `openhuman-core run`.
pub fn desktop() -> Self {
Self {
rpc_http: true,
socketio: true,
cron: true,
channels: true,
login_gated: true,
update_scheduler: true,
memory_queue: true,
skill_catalog_refresh: true,
mcp_boot: true,
integrations: true,
memory_sync: true,
}
}
/// HTTP JSON-RPC only — a single-core cloud/server deployment. No Socket.IO,
/// no cron/channels/login-gated services; the supervisor decides those per plan.
pub fn headless_api() -> Self {
Self {
rpc_http: true,
socketio: false,
cron: false,
channels: false,
login_gated: false,
update_scheduler: false,
memory_queue: false,
skill_catalog_refresh: false,
mcp_boot: false,
integrations: false,
memory_sync: false,
}
}
/// No transport and no background services — for library / harness embedders
/// that only drive the core through [`CoreRuntime::invoke`] and agent turns.
pub fn none() -> Self {
Self {
rpc_http: false,
socketio: false,
cron: false,
channels: false,
login_gated: false,
update_scheduler: false,
memory_queue: false,
skill_catalog_refresh: false,
mcp_boot: false,
integrations: false,
memory_sync: false,
}
}
/// A long-lived embedded host: no transport, but the background work such
/// a session expects.
///
/// Named for the shape, not a consumer — see [`DomainSet::embedded`].
///
/// `rpc_http: false` is the payoff of embedding through the typed facade
/// rather than HTTP — no port bound, no bearer-token handshake, no
/// loopback listener. Flip it on only if the host also needs to serve external clients.
///
/// `socketio` stays off because an embedded host reads state through the
/// facade and the core event bus in-process; `channels` stays off because
/// such a host owns its own harness and networking transports.
pub fn embedded() -> Self {
Self {
rpc_http: false,
socketio: false,
cron: true,
channels: false,
login_gated: true,
update_scheduler: false,
memory_queue: true,
skill_catalog_refresh: true,
mcp_boot: false,
integrations: false,
memory_sync: true,
}
}
}
/// How the per-process RPC bearer token is seeded.
pub enum TokenSource {
/// An in-memory bearer supplied by the embedder (the Tauri shell hands its
/// `CoreProcessHandle.rpc_token` this way). Seeded via
/// [`crate::core::auth::init_rpc_token_with_value`] — never crosses the
/// process environment.
Fixed(Arc<String>),
/// Standalone fallback: read `OPENHUMAN_CORE_TOKEN` from the environment when
/// present (operator config), otherwise generate a fresh token and write
/// `{root}/core.token` (0o600 on Unix) so CLI callers can authenticate.
EnvOrFile,
}
/// Startup work a core runtime performs before it can dispatch in-process RPC.
///
/// Normal runtimes load their workspace stores, bootstrap subscribers and
/// recover interrupted work. Inspection runtimes require a supplied config and
/// fixed bearer, then construct a real context without those persistent boot
/// effects. The selected RPC operation still decides which reads, network
/// probes and opt-in live writes it performs.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub enum CoreBootMode {
/// Initialize workspace stores and runtime infrastructure as usual.
#[default]
Normal,
/// Build a dispatchable context without startup persistence or services.
Inspection,
}
/// Builder for a [`CoreRuntime`]. Construct with [`CoreBuilder::new`], then
/// [`CoreBuilder::build`] to initialize the core.
pub struct CoreBuilder {
host_kind: HostKind,
boot_mode: CoreBootMode,
token: TokenSource,
services: ServiceSet,
domains: DomainSet,
tool_groups: crate::tools::toolpacks::ToolGroups,
host: Option<String>,
port: Option<u16>,
config: Option<crate::config::Config>,
extensions: crate::core::slots::Extensions,
}
impl CoreBuilder {
/// Start a builder for the given host kind. Defaults: [`TokenSource::EnvOrFile`],
/// [`ServiceSet::desktop`], and [`DomainSet::full`].
pub fn new(host_kind: HostKind) -> Self {
Self {
host_kind,
boot_mode: CoreBootMode::Normal,
token: TokenSource::EnvOrFile,
services: ServiceSet::desktop(),
domains: DomainSet::full(),
tool_groups: Default::default(),
host: None,
port: None,
config: None,
extensions: crate::core::slots::Extensions::new(),
}
}
/// Select normal startup or a side-effect-limited inspection context.
///
/// [`CoreBootMode::Inspection`] requires [`Self::config`] and a
/// [`TokenSource::Fixed`] bearer. It never discovers an ambient config,
/// opens or installs a storage backend, initializes workspace stores,
/// recovers prior work, or starts background services.
pub fn boot_mode(mut self, mode: CoreBootMode) -> Self {
self.boot_mode = mode;
self
}
/// Binds hook registrations (see [`crate::core::slots`]) to the context
/// this builder creates, ahead of any process-wide registration. Fill an
/// [`Extensions`](crate::core::slots::Extensions) with
/// [`HookSlot::register_in`](crate::core::slots::HookSlot::register_in)
/// and pass it here; derived per-agent contexts inherit it.
pub fn extensions(mut self, extensions: crate::core::slots::Extensions) -> Self {
self.extensions = extensions;
self
}
/// Choose which background services and transports this runtime runs.
pub fn services(mut self, services: ServiceSet) -> Self {
self.services = services;
self
}
/// Choose which domain families exist at runtime (default [`DomainSet::full`]).
/// `harness()` builds the embeddable agent core; `none()` disables every
/// domain family while retaining transport built-ins and core infrastructure.
pub fn domains(mut self, domains: DomainSet) -> Self {
self.domains = domains;
self
}
/// Choose how each tool group reaches the model (default: every group
/// withheld behind `use_skill`, the desktop app's shape).
///
/// The third narrowing axis, independent of both `services` and `domains`:
/// `ServiceSet` picks the background services, `DomainSet` picks which
/// families exist, and this picks 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.
///
/// ```no_run
/// # use openhuman_core::core::runtime::CoreBuilder;
/// # use openhuman_core::tools::toolpacks::{GroupMode, ToolGroups};
/// # fn f(b: CoreBuilder) -> CoreBuilder {
/// b.tool_groups(
/// ToolGroups::none()
/// .with("documents", GroupMode::Advertised)
/// .with("workflows", GroupMode::Withheld),
/// )
/// # }
/// ```
///
/// Narrowing only: a group set to `Advertised` whose tools are compiled
/// out, or whose `DomainGroup` is off under `domains`, stays absent.
pub fn tool_groups(mut self, tool_groups: crate::tools::toolpacks::ToolGroups) -> Self {
self.tool_groups = tool_groups;
self
}
/// Choose how the RPC bearer token is seeded.
pub fn token(mut self, token: TokenSource) -> Self {
self.token = token;
self
}
/// Override the bind host (default: `OPENHUMAN_CORE_HOST` env or `127.0.0.1`).
pub fn host(mut self, host: impl Into<String>) -> Self {
self.host = Some(host.into());
self
}
/// Override the bind port (default: `OPENHUMAN_CORE_PORT` env or `7788`).
pub fn port(mut self, port: u16) -> Self {
self.port = Some(port);
self
}
/// Supply the [`Config`](crate::config::Config) outright instead
/// of letting `build()` discover one from `config.toml` and the environment.
///
/// Without this an embedder can only configure the core by setting
/// environment variables before `build()` — process-global, order-dependent
/// relative to a call it does not appear in, and silently wrong if a later
/// caller in the same process wants different values. With it, every knob
/// the core reads from config (workspace, action dir, autonomy tier, MCP
/// servers, provider routes) is an ordinary struct field.
///
/// The config is used **verbatim**: no `config.toml` read and no env
/// overlay. Call
/// [`apply_env_overrides`](crate::config::Config::apply_env_overrides)
/// yourself first if you want the environment to participate.
pub fn config(mut self, config: crate::config::Config) -> Self {
self.config = Some(config);
self
}
/// Root the core's state at `dir` — sessions, memory, attachments, skills.
///
/// Sugar over [`config`](Self::config) for the common case of "same
/// configuration, different workspace"; starts from the config already
/// supplied, or [`Config::default`](Default::default) when none is.
pub fn workspace(mut self, dir: impl Into<std::path::PathBuf>) -> Self {
let dir = dir.into();
let mut config = self.config.take().unwrap_or_default();
config.workspace_dir = dir.clone();
// Credential profiles and the file-backed keyring resolve from
// `config_path`'s parent, not from `workspace_dir`. Rooting only the
// workspace while leaving the default config path would keep sessions
// and credentials in the previous config root even though this method
// documents `dir` as rooting "core state" — so set a deterministic
// config path beside the workspace, mirroring the harness's `Dir`
// layout (`<root>/config.toml` next to `<root>/workspace`).
config.config_path = dir.join("config.toml");
self.config = Some(config);
self
}
/// Set the agent's read/write root for acting tools (`action_dir`).
///
/// Sugar over [`config`](Self::config), like [`workspace`](Self::workspace).
/// Distinct from the workspace on purpose: the workspace holds internal
/// state the agent must never write to, and `is_workspace_internal_path`
/// enforces that separation fail-closed.
pub fn action_dir(mut self, dir: impl Into<std::path::PathBuf>) -> Self {
let mut config = self.config.take().unwrap_or_default();
config.action_dir = dir.into();
self.config = Some(config);
self
}
/// Point the core's backend calls at `url` (`Config::api_url`).
///
/// Sugar over [`config`](Self::config), like [`workspace`](Self::workspace).
/// Worth having as its own method because the value reaches more than the
/// obvious client: `/auth/me` session validation, the hosted-backend
/// surfaces all resolve through it. A host that sets only one of
/// those has the other two pointing at a different deployment, which fails
/// as "backend rejected session token" rather than as a mismatch.
pub fn backend_url(mut self, url: impl Into<String>) -> Self {
let mut config = self.config.take().unwrap_or_default();
config.api_url = Some(url.into());
self.config = Some(config);
self
}
/// Initialize the core: register controllers, load the master key, seed the
/// RPC bearer, initialize workspace-bound stores, and run
/// [`bootstrap_core_runtime`]. Binds no port and starts no transport.
///
/// The init sequence itself is owned by [`CoreContext::init`] (Phase 2,
/// Stage A).
pub async fn build(self) -> anyhow::Result<CoreRuntime> {
if self.boot_mode == CoreBootMode::Inspection {
anyhow::ensure!(
self.config.is_some(),
"inspection boot requires a caller-supplied config"
);
anyhow::ensure!(
matches!(&self.token, TokenSource::Fixed(_)),
"inspection boot requires a process-local fixed RPC bearer"
);
anyhow::ensure!(
crate::storage::installed().is_none(),
"inspection boot requires no installed storage backend"
);
}
let (ctx, has_operator_token, config) = CoreContext::init_with_boot_mode(
self.host_kind,
&self.token,
self.domains,
self.tool_groups.clone(),
self.config,
self.boot_mode,
)
.await?;
ctx.extensions().merge_from(&self.extensions);
let components = config
.as_ref()
.map(|c| ComponentSet::from_config(&c.components))
.unwrap_or_else(ComponentSet::all);
// Retired scheduled jobs must be pruned before `build()` exposes
// in-process RPC or agent turns. Running this from `serve()` is too
// late for embedders that only build and invoke.
if self.boot_mode == CoreBootMode::Normal {
if let Some(cfg) = config.as_ref() {
crate::core::runtime::services::run_legacy_migrations(cfg).await;
}
}
// Reap agent runs orphaned by a previous process (crash / restart /
// deploy). Here, and not with the other boot-once jobs, because those
// run from `serve()`: an embedder that only calls `build()` and then
// `invoke()` never reaches them, and `openhuman.agent_runs_active` is
// dispatchable the moment this returns. The core is a single in-process
// runtime, so a run left Pending/Running/Interrupted in the durable
// status store has no executor to advance it and would be listed as
// active forever. Best-effort — a store that cannot be read logs and
// reaps nothing rather than failing the build.
if self.boot_mode == CoreBootMode::Normal {
if let Some(cfg) = config.as_ref() {
crate::agent::tinyagents::reaper::reap_orphaned_runs(&cfg.workspace_dir).await;
}
}
Ok(CoreRuntime {
ctx,
config,
services: if self.boot_mode == CoreBootMode::Inspection {
ServiceSet::none()
} else {
components.narrow_services(self.services)
},
has_operator_token,
host: self.host,
port: self.port,
service_tasks: crate::core::runtime::services::ServiceTasks::default(),
})
}
}
/// A built, initialized core. Dispatch RPC in-process with [`CoreRuntime::invoke`],
/// start its background services with [`CoreRuntime::start_services`], or hand it
/// to `openhuman_rpc::server::serve` to run the selected transport as well.
pub struct CoreRuntime {
ctx: Arc<CoreContext>,
config: Option<Config>,
services: ServiceSet,
has_operator_token: bool,
host: Option<String>,
port: Option<u16>,
/// The background services [`start_services`](Self::start_services)
/// started; aborted by [`stop_services`](Self::stop_services) and when
/// the runtime drops.
service_tasks: crate::core::runtime::services::ServiceTasks,
}
impl CoreRuntime {
/// The services/transports this runtime is configured to run.
pub fn services(&self) -> ServiceSet {
self.services
}
/// The initialized core context (host identity + resolved workspace).
pub fn context(&self) -> &Arc<CoreContext> {
&self.ctx
}
/// Dispatch an RPC method in-process — the same path the HTTP `/rpc` handler
/// and the CLI use ([`crate::core::invoke::invoke_method`]). No network involved.
pub async fn invoke(
&self,
method: &str,
params: serde_json::Value,
) -> Result<serde_json::Value, String> {
self.invoke_in(Arc::clone(&self.ctx), method, params).await
}
/// [`invoke`](Self::invoke) under a caller-supplied context instead of the
/// runtime's own — typically a per-agent child from
/// [`CoreContext::derive_with`], so the handler's config loader, DomainSet
/// gate and tool-group filter all read that agent's overlay.
pub async fn invoke_in(
&self,
ctx: Arc<CoreContext>,
method: &str,
params: serde_json::Value,
) -> Result<serde_json::Value, String> {
log::trace!("[core-runtime] invoke_in method={method}");
CoreContext::scope(
Arc::clone(&ctx),
crate::core::invoke::invoke_method(
crate::core::runtime::DispatchCtx::new(ctx),
crate::core::invoke::default_state(),
method,
params,
),
)
.await
}
/// Run an arbitrary future with `ctx` as the ambient [`CoreContext`] — the
/// native (non-RPC) counterpart of [`invoke_in`](Self::invoke_in) for
/// callers that reach a domain operation directly, such as an embedded
/// agent turn. Bypasses the registered-RPC dispatch gate, so the caller is
/// responsible for honouring `ctx.domains()` itself.
pub async fn run_in<F: std::future::Future>(&self, ctx: Arc<CoreContext>, fut: F) -> F::Output {
CoreContext::scope(ctx, fut).await
}
/// The host this runtime was built to bind, when the builder set one.
pub fn host(&self) -> Option<&str> {
self.host.as_deref()
}
/// The port this runtime was built to bind, when the builder set one.
pub fn port(&self) -> Option<u16> {
self.port
}
/// Whether the RPC bearer came from the operator (env or an in-memory
/// handoff) rather than the self-generated `{workspace}/core.token`. A
/// server must not bind a public address without one (#1919).
pub fn has_operator_token(&self) -> bool {
self.has_operator_token
}
/// Record that a transport bound its listener at `local_addr`.
pub fn listener_bound(&self, local_addr: std::net::SocketAddr) {
#[cfg(feature = "modules")]
crate::desktop::control::set_listener_is_loopback(local_addr.ip().is_loopback());
#[cfg(not(feature = "modules"))]
let _ = local_addr;
}
/// Cleanup to run once a transport has stopped serving, whether it ended
/// cleanly or with an error.
///
/// Memory holds nothing to flush: turns are logged as they happen and
/// queued background jobs are persisted. There is no local model runtime
/// to stop either: the user runs Ollama / LM Studio / MLX themselves and
/// OpenHuman never spawns it.
pub async fn exit_cleanup(&self) {
if let Err(error) = crate::integrations::composio::trigger_history::close_global(
&crate::core::runtime::DispatchCtx::new(Arc::clone(&self.ctx)),
)
.await
{
log::warn!("[composio][history] archive shutdown failed: {error}");
}
log::debug!("[core] shutdown: exit cleanup done (no owned local runtime to stop)");
}
/// Spawn each selected background service.
///
/// A transport calls this once its listener is bound, so a failed bind
/// never leaves pollers, one-shot jobs, MCP processes or socket
/// reconnect work running without a live runtime. A runtime with no
/// transport calls it directly.
///
/// Idempotent while they run; the long-lived loops stop with
/// [`stop_services`](Self::stop_services) or when this runtime drops.
pub async fn start_services(&self) {
crate::core::runtime::services::start_selected_services(
&self.service_tasks,
self.services,
self.config.as_ref(),
&self.ctx,
)
.await;
}
/// Stop the services [`start_services`](Self::start_services) started
/// (they may be restarted). Also runs on drop.
pub fn stop_services(&self) {
self.service_tasks.stop();
}
}
#[cfg(test)]
#[path = "builder_tests.rs"]
mod tests;