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
//! Assembling a [`Runtime`](super::Runtime): the builder and its knobs.
//!
//! The builder turns typed inputs into one in-memory base [`Config`] plus a
//! [`DomainSet`]/[`ServiceSet`]/[`ToolGroups`] triple, installs the API key
//! into the credential store, installs the host's process-global seams, and
//! hands everything to [`CoreBuilder`](openhuman_core::core::runtime::CoreBuilder).
//! Nothing here mutates the process environment.
//!
//! The pieces live beside this file: [`presets`](super::presets) (the
//! per-host starting points), [`seams`](super::seams) (process-global
//! installers restored on drop), `build.rs` (the boot sequence) and `run.rs`
//! (the CLI entry).
use std::path::PathBuf;
use std::sync::Arc;
use openhuman_core::config::Config;
use openhuman_core::core::runtime::{CoreBootMode, DomainSet, ServiceSet, TokenSource};
use openhuman_core::core::types::HostKind;
use openhuman_core::tools::toolpacks::ToolGroups;
use tinyagents_session::port::SessionStoreProvider;
use super::seams::HostSeams;
use super::ApiKey;
use crate::harness::{Access, Provider, Workspace};
use crate::Session;
// Re-exported for the sibling test module and older call sites that reached
// the default triples through this module.
pub(crate) use super::build::apply_provider;
/// Whether `services` asks for any background work.
pub(crate) fn requests_background_services(services: ServiceSet) -> bool {
services != ServiceSet::none()
}
/// Whether [`RuntimeBuilder::build`] starts `services` itself: only when they
/// ask for background work and the host did not
/// [defer](RuntimeBuilder::defer_services) them.
pub(crate) fn starts_services_on_build(services: ServiceSet, deferred: bool) -> bool {
!deferred && requests_background_services(services)
}
#[cfg(test)]
pub(crate) use super::build::{effective_host_kind, routed_provider_effective};
#[cfg(test)]
pub(crate) use super::presets::{default_domains, default_services};
#[cfg(test)]
pub(crate) use super::{RuntimeError, RUNTIME_LIVE};
/// Who produces the [`Config`] the core boots with.
///
/// The choice is not cosmetic. A config the core is *handed* makes it a
/// scoped embedder: credentials live under that config's root, the operator's
/// `active_user.toml` is never read or written, and handlers see that exact
/// config for the life of the process. A config the core *discovers* is the
/// operator's install, re-read from `config.toml` and the environment, with
/// per-user activation — what the desktop app, the CLI and the TUI run.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ConfigSource {
/// The builder resolves the config — from the [`Workspace`], a supplied
/// [`RuntimeBuilder::config`], and the other knobs — and hands it to the
/// core verbatim. The library default.
#[default]
Resolved,
/// The core discovers its config itself, exactly as a desktop, CLI or TUI
/// host does. Requires [`Workspace::Inherit`]; refuses the knobs that
/// would edit a config (`config`, `backend_url`, `workspace_dir`,
/// `action_dir`, `api_key`), because there is no config in hand to edit.
/// [`RuntimeBuilder::access`] and [`RuntimeBuilder::provider`] then only
/// set the defaults of agents created with [`crate::Runtime::agent`](super::Runtime::agent).
Discovered,
}
/// Builder for a [`Runtime`](super::Runtime). Obtain with
/// [`crate::Runtime::builder`](super::Runtime::builder) or one of the host presets
/// ([`RuntimeBuilder::library`], [`desktop`](RuntimeBuilder::desktop),
/// [`cli`](RuntimeBuilder::cli), [`tui`](RuntimeBuilder::tui)).
pub struct RuntimeBuilder {
pub(super) workspace: Workspace,
pub(super) workspace_dir: Option<PathBuf>,
pub(super) action_dir: Option<PathBuf>,
pub(super) config_source: ConfigSource,
pub(super) boot_mode: CoreBootMode,
pub(super) provider: Provider,
pub(super) access: Access,
pub(super) services: Option<ServiceSet>,
pub(super) defer_services: bool,
pub(super) domains: Option<DomainSet>,
pub(super) tool_groups: Option<ToolGroups>,
pub(super) host_kind: HostKind,
pub(super) token: TokenSource,
pub(super) listen_host: Option<String>,
pub(super) listen_port: Option<u16>,
pub(super) config: Option<Config>,
pub(super) session: Option<Session>,
pub(super) backend_url: Option<String>,
pub(super) api_key: Option<ApiKey>,
pub(super) memory_engine: Option<Arc<dyn tinymemory_api::MemoryEngine>>,
pub(super) session_store: Option<Arc<dyn SessionStoreProvider>>,
pub(super) cron_delivery: Option<Arc<dyn openhuman_core::cron::host_delivery::CronDelivery>>,
pub(super) cron_job_handlers: Vec<(crate::cron::JobKind, Arc<dyn crate::cron::JobKindHandler>)>,
pub(super) seams: HostSeams,
pub(super) max_agents: usize,
pub(super) agent_defaults: super::AgentDefaults,
pub(super) config_knobs: super::info::ConfigKnobs,
pub(super) selection: Option<super::ModuleSelection>,
}
/// Live agents a runtime hosts unless [`RuntimeBuilder::max_agents`] says
/// otherwise.
pub const DEFAULT_MAX_AGENTS: usize = 1024;
impl Default for RuntimeBuilder {
fn default() -> Self {
Self::new()
}
}
impl RuntimeBuilder {
/// A builder with safe defaults: an ephemeral workspace, the machine's
/// configured inference, the supervised access tier, no background
/// services, and every domain a library agent can use. Same as
/// [`RuntimeBuilder::library`].
pub fn new() -> Self {
Self {
workspace: Workspace::default(),
workspace_dir: None,
action_dir: None,
config_source: ConfigSource::Resolved,
boot_mode: CoreBootMode::Normal,
provider: Provider::inherit(),
access: Access::default(),
services: None,
defer_services: false,
domains: None,
tool_groups: None,
host_kind: HostKind::Library,
token: TokenSource::EnvOrFile,
listen_host: None,
listen_port: None,
config: None,
session: None,
backend_url: None,
api_key: None,
memory_engine: None,
session_store: None,
cron_delivery: None,
cron_job_handlers: Vec::new(),
seams: HostSeams::default(),
max_agents: DEFAULT_MAX_AGENTS,
agent_defaults: super::AgentDefaults::default(),
config_knobs: super::info::ConfigKnobs::default(),
selection: None,
}
}
/// Replace the runtime-wide agent defaults. Explicit individual setters still win.
pub fn agent_defaults(mut self, defaults: super::AgentDefaults) -> Self {
self.provider = defaults.provider.clone();
self.access = defaults.access.clone();
self.domains = Some(defaults.domains);
self.tool_groups = Some(defaults.tool_groups.clone());
self.agent_defaults = defaults;
self
}
/// Sampling defaults inherited by agents and then overridden per turn.
pub fn model_defaults(mut self, model: super::ModelDefaults) -> Self {
self.agent_defaults.model = model;
self
}
/// Default confinement for new agents.
pub fn sandbox(mut self, mode: crate::SandboxModeSpec) -> Self {
self.agent_defaults.sandbox = mode;
self
}
/// Default definition extended by each agent.
pub fn definition_base(mut self, definition: crate::AgentDefinitionSpec) -> Self {
self.agent_defaults.definition = definition;
self
}
/// Runtime-wide skill installation and discovery policy.
pub fn skills(mut self, policy: super::SkillsPolicy) -> Self {
self.agent_defaults.skills = policy;
self
}
/// Servers inherited by every agent, with agent declarations added afterwards.
#[cfg(feature = "mcp")]
pub fn mcp_baseline(mut self, servers: impl IntoIterator<Item = crate::McpServer>) -> Self {
self.agent_defaults.mcp_baseline = servers.into_iter().collect();
self
}
/// Detailed autonomy settings; access tiers are subsequently applied to each agent.
pub fn autonomy(mut self, value: openhuman_core::config::schema::AutonomyConfig) -> Self {
self.config_knobs.autonomy = Some(value);
self
}
/// Tool rules applied to every agent, which agents may only narrow.
pub fn tool_rules(mut self, value: tinytools::ToolRules) -> Self {
self.config_knobs.tool_rules = Some(value);
self
}
/// Data egress policy for this runtime.
pub fn privacy(mut self, value: openhuman_core::config::schema::PrivacyConfig) -> Self {
self.config_knobs.privacy = Some(value);
self
}
/// Credential encryption policy.
pub fn secrets(mut self, value: openhuman_core::config::schema::SecretsConfig) -> Self {
self.config_knobs.secrets = Some(value);
self
}
/// Background memory learning defaults.
pub fn learning(mut self, value: super::LearningSettings) -> Self {
self.config_knobs.learning = Some(value);
self
}
/// Cron scheduler configuration; `services` separately controls its lifecycle.
pub fn cron(mut self, value: openhuman_core::config::schema::CronConfig) -> Self {
self.config_knobs.cron = Some(value);
self
}
/// The memory engine every agent and [`crate::Runtime::memory`](super::Runtime::memory)
/// use, in place of the configured `[memory]` engine (TinyHumans over the
/// backend credential, or CortexDB with a stored key).
///
/// For a host that owns its memory store, or a test that wants
/// TinyMemory's in-memory reference engine: memory then runs without a
/// TinyHumans credential. The engine's writes are scrubbed like any
/// other's. It is process-wide, as the runtime is, and the core has no
/// uninstall for it: it stays installed for the life of the process.
pub fn memory_engine(mut self, engine: Arc<dyn tinymemory_api::MemoryEngine>) -> Self {
self.memory_engine = Some(engine);
self
}
/// Where every agent's conversations are kept, in place of files under
/// the workspace: transcripts, the turn journal and run status, goals and
/// todos, each agent's apart from every other's (the provider is asked for
/// the stores of the agent's id).
///
/// For a host serving many users from one process out of its own
/// database; pair it with [`Workspace::Stateless`] so nothing durable is
/// left on disk. A provider from the `testkit` feature can keep everything
/// in memory. It is process-wide, as the runtime is, and
/// is removed with the runtime.
pub fn session_store(mut self, provider: Arc<dyn SessionStoreProvider>) -> Self {
self.session_store = Some(provider);
self
}
/// Route the replies of the agents' scheduled jobs yourself.
///
/// An `origin`-mode run of an agent's cron job hands its output to
/// [`CronDelivery::deliver`](crate::CronDelivery::deliver) with the agent
/// id, the thread the job was created in and its
/// [`JobOrigin`](crate::JobOrigin), instead of writing into a local thread
/// or channel. A failed run is never delivered, nor is `NO_REPLY` from a
/// job whose prompt allows it; any other job always delivers a message.
/// Jobs still run only while their agent is live (the scheduler service
/// must be on). It is process-wide, as the runtime is, and the core has no
/// uninstall for it: it stays installed for the life of the process.
pub fn cron_delivery(
mut self,
delivery: Arc<dyn openhuman_core::cron::host_delivery::CronDelivery>,
) -> Self {
self.cron_delivery = Some(delivery);
self
}
/// Run scheduled jobs of `kind` through `handler` instead of the built-in
/// one (see [`Runtime::register_job_handler`](crate::Runtime::register_job_handler)).
/// Registered when the runtime is built and restored when it drops, so a
/// host can swap how `shell`, `agent` or `flow` jobs run without touching
/// cron internals. Call it once per kind; a later call replaces an earlier
/// one for the same kind.
pub fn cron_job_handler(
mut self,
kind: crate::cron::JobKind,
handler: Arc<dyn crate::cron::JobKindHandler>,
) -> Self {
self.cron_job_handlers
.retain(|(existing, _)| *existing != kind);
self.cron_job_handlers.push((kind, handler));
self
}
/// The most agents this runtime hosts at once; [`crate::Runtime::agent`]
/// returns [`AgentError::AgentLimit`](crate::AgentError::AgentLimit)
/// beyond it. Removed and dropped agents do not count. Defaults to
/// [`DEFAULT_MAX_AGENTS`].
pub fn max_agents(mut self, limit: usize) -> Self {
self.max_agents = limit;
self
}
/// Where the runtime keeps its credential store, session database and
/// every agent's memory, transcripts and skills.
///
/// [`workspace_dir`](Self::workspace_dir) and
/// [`action_dir`](Self::action_dir) refine the paths this resolves to.
pub fn workspace(mut self, workspace: Workspace) -> Self {
self.workspace = workspace;
self
}
/// Put the core's internal state (`config.workspace_dir`: session
/// database, memory, attachments, every agent's `agents/<id>/` home) at
/// exactly `dir`, created if absent.
///
/// Applied **after** the [`Workspace`] is resolved and only to that one
/// field: the credential root (`config_path`'s parent) stays where the
/// `Workspace` put it, so this splits state from credentials rather than
/// moving both. Use [`Workspace::Dir`] to move everything together.
/// Not available with [`ConfigSource::Discovered`].
pub fn workspace_dir(mut self, dir: impl Into<PathBuf>) -> Self {
self.workspace_dir = Some(dir.into());
self
}
/// The runtime-wide read/write root for acting tools (`config.action_dir`),
/// created if absent. Agents may still name their own.
///
/// Overrides the sibling `action/` directory an ephemeral or `Dir`
/// workspace would otherwise create, and the operator's configured
/// `action_dir` under [`Workspace::Inherit`]. Keep it outside the
/// workspace: acting tools are refused inside it. Not available with
/// [`ConfigSource::Discovered`].
pub fn action_dir(mut self, dir: impl Into<PathBuf>) -> Self {
self.action_dir = Some(dir.into());
self
}
/// Who produces the boot [`Config`]; see [`ConfigSource`]. The host
/// presets other than [`library`](Self::library) pick
/// [`ConfigSource::Discovered`].
pub fn config_source(mut self, source: ConfigSource) -> Self {
self.config_source = source;
self
}
/// Choose normal host startup or a side-effect-limited inspection build.
///
/// Inspection requires an inherited workspace, a supplied resolved
/// config, and a fixed in-memory bearer. It does not discover ambient
/// config, open persistent storage, install session stores, bootstrap
/// workspace state, or start background services. The runtime still has
/// a real `CoreContext` and can dispatch in-process RPC.
pub fn boot_mode(mut self, mode: CoreBootMode) -> Self {
self.boot_mode = mode;
self
}
/// The TinyHumans API key — the runtime's only credential.
///
/// Installed into the runtime's credential store before the core boots.
/// Managed inference then sends it as a bearer to the TinyHumans
/// OpenAI-compatible endpoint and backend REST calls send it as
/// `x-api-key`; no user session is involved. Agents that name their own
/// [`Provider`] never use it.
pub fn api_key(mut self, key: impl Into<ApiKey>) -> Self {
self.api_key = Some(key.into());
self
}
/// Point the core's backend calls at `url`.
///
/// Unset means whatever [`Config`] resolves to — for a fresh config the
/// hosted TinyHumans backend. Set it to a stub or a self-hosted backend
/// when the runtime should not reach the real one.
pub fn backend_url(mut self, url: impl Into<String>) -> Self {
self.backend_url = Some(url.into());
self
}
/// Default provider for agents that do not name one.
pub fn provider(mut self, provider: Provider) -> Self {
self.provider = provider;
self
}
/// Default access tier for agents that do not name one. Defaults to
/// [`Access::supervised`].
pub fn access(mut self, access: Access) -> Self {
self.access = access;
self
}
/// Override which background services run.
///
/// The library default is deliberately minimal (no services): cron, the
/// login-gated services and the memory queue each write
/// to the workspace on their own schedule, turning a library call into a
/// background process the caller did not ask for.
///
/// A set that selects background work (`cron: true` to let
/// [`crate::Runtime::cron`] jobs fire on their own, say) is started by
/// [`build`](Self::build) and stopped when the runtime drops; see
/// [`crate::Runtime::start_services`] / [`crate::Runtime::stop_services`]. Starting is
/// idempotent, so a transport that serves the runtime
/// (`openhuman-rpc`) and calls `start_services` once its listener is
/// bound does not start them twice.
pub fn services(mut self, services: ServiceSet) -> Self {
self.services = Some(services);
self
}
/// Build without starting the background services the [`ServiceSet`]
/// selects; the host starts them with
/// [`Runtime::start_services`](crate::Runtime::start_services) once it is
/// ready.
///
/// For a host that registers
/// [`Runtime::on_system_job`](crate::Runtime::on_system_job) handlers:
/// a job stored by an earlier process can be due the moment the
/// scheduler starts, and a system job with no handler yet is announced
/// and recorded `ok` without running. Build deferred, register every
/// handler, upsert the jobs, then start.
pub fn defer_services(mut self) -> Self {
self.defer_services = true;
self
}
/// Override which domain families exist at runtime.
///
/// Families are registered once, at boot, so an agent can only *narrow*
/// this set. The library default is [`DomainSet::embedded`] plus `mcp`
/// and `skills` when those features are compiled in — the runtime cannot
/// know yet which agents will declare servers or skills, and an agent
/// that declares none narrows them back off for itself.
pub fn domains(mut self, domains: DomainSet) -> Self {
self.domains = Some(domains);
self
}
/// Default tool-group disclosure. Agents may narrow it.
///
/// Defaults to every group withheld behind `use_skill`, matching the
/// desktop app. See [`ToolGroups::advertised`] and [`ToolGroups::none`].
pub fn tool_groups(mut self, tool_groups: ToolGroups) -> Self {
self.tool_groups = Some(tool_groups);
self
}
/// Identify the host to the core. Defaults to [`HostKind::Library`],
/// which accepts caller-supplied provider credentials without an
/// OpenHuman app login.
pub fn host_kind(mut self, host_kind: HostKind) -> Self {
self.host_kind = host_kind;
self
}
/// How the per-process RPC bearer is seeded. Defaults to
/// [`TokenSource::EnvOrFile`]: `OPENHUMAN_CORE_TOKEN` when set, otherwise
/// a fresh token written to `core.token` beside the config. A host that
/// already holds the bearer in memory (the desktop shell) passes
/// [`TokenSource::Fixed`] so it never crosses the environment.
pub fn token(mut self, token: TokenSource) -> Self {
self.token = token;
self
}
/// The address a transport serving this runtime binds.
///
/// Recorded on the core runtime only: the runtime binds nothing itself.
/// A piece left unset falls back, at serve time, to `OPENHUMAN_CORE_HOST`
/// / `OPENHUMAN_CORE_PORT` and then `127.0.0.1:7788`. See also
/// [`listen_host`](Self::listen_host) and [`listen_port`](Self::listen_port)
/// for setting one half.
pub fn listen(self, host: impl Into<String>, port: u16) -> Self {
self.listen_host(host).listen_port(port)
}
/// The bind host alone; see [`listen`](Self::listen).
pub fn listen_host(mut self, host: impl Into<String>) -> Self {
self.listen_host = Some(host.into());
self
}
/// The bind port alone; see [`listen`](Self::listen).
pub fn listen_port(mut self, port: u16) -> Self {
self.listen_port = Some(port);
self
}
/// Install an app session before the first turn.
///
/// Kept for hosts that drive authenticated backend features on behalf of
/// a signed-in user. A runtime with an [`api_key`](Self::api_key) does not
/// need one.
pub fn session(mut self, session: Session) -> Self {
self.session = Some(session);
self
}
/// Start from a caller-supplied [`Config`] instead of the default.
///
/// Every other builder method is applied **on top** of it, and every
/// agent starts from the result, so this is the escape hatch for the
/// config fields the builder does not model — not a way to bypass them.
pub fn config(mut self, config: Config) -> Self {
self.config = Some(config);
self
}
}
#[cfg(test)]
#[path = "builder_tests.rs"]
mod tests;