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
//! The shared host boot: one entry per host shape, so each host's `main`
//! becomes a few lines instead of a hand-assembled sequence.
//!
//! | Entry | Replaces | Builder |
//! |---|---|---|
//! | [`cli`] | `tinyhumans::install` → the server launcher → `run_core_from_args` | [`cli_builder`]: the `cli` preset, connected, with the server launcher and the `http_host` controllers |
//! | [`desktop`] | `tinyhumans::install` + the embedded server entry | [`desktop_builder`]: the `desktop` preset, connected, with the bearer, listener, services, server launcher and `http_host` controllers |
//! | [`tui`] | `tinyhumans::install` + `session_store::install_for_host` + `CoreBuilder(full, none)` | [`tui_builder`]: the `tui` preset, connected ([`tui`] adds the storage-backed session store) |
//!
//! Each `*_builder` returns a [`tinyhumans::RuntimeBuilder`] so a host can
//! adjust it (product identity, hooks, a different ranker) before handing it
//! to the matching `serve_*` / `build` call.
//!
//! "Connected" means [`tinyhumans::RuntimeBuilder::connect`]: the SDK
//! transport (process global and bound to the runtime), the hosted RPC
//! proxies and, with the `jev` feature, the Jev `tool_search` ranker.
//!
//! # Behavior notes
//!
//! - The desktop and CLI servers install the storage-backed session store for
//! the life of the process (see `server::shims::build_and_serve`), exactly as
//! the `run_server*` shims do; the TUI hands it to the builder, which
//! restores the previous provider when its runtime drops at exit. Both
//! resolve one storage URL (`OPENHUMAN_STORAGE_URL`, else `[storage] url`,
//! else `sqlite:<workspace>/storage`).
//! - Builder seams follow embed's install/restore rules: the hosted and
//! `http_host` controllers and the server launcher stay for the process; the
//! Jev ranker is restored when the runtime drops. A desktop server that
//! restarts in place re-installs it on the next build.
//! - The runtime does not start background services itself; [`desktop`]
//! starts them through `server::serve`, as the shims always have.
//!
//! [`tinyhumans::RuntimeBuilder`]: openhuman_tinyhumans::RuntimeBuilder
//! [`tinyhumans::RuntimeBuilder::connect`]: openhuman_tinyhumans::RuntimeBuilder::connect
#[cfg(feature = "server")]
use std::sync::Arc;
#[cfg(feature = "server")]
use openhuman_tinyhumans::embed::{
ConfigSource, CoreBootMode, RuntimeConfig, ServiceSet, TokenSource, Workspace,
};
use openhuman_tinyhumans::RuntimeBuilder;
#[cfg(feature = "server")]
use tokio_util::sync::CancellationToken;
#[cfg(feature = "server")]
pub use crate::server::EmbeddedReadySignal;
#[path = "host/secret_storage.rs"]
mod secret_storage;
#[cfg(feature = "server")]
#[path = "host/doctor_cli.rs"]
mod doctor_cli;
/// The CLI host's builder: the `cli` preset with this crate's server as the
/// `run` / `serve` launcher and the `http_host.*` controllers registered.
#[cfg(feature = "server")]
pub fn cli_builder() -> RuntimeBuilder {
RuntimeBuilder::cli()
.server_launcher(crate::server::cli::launch)
.controller_extension(crate::http_host::extension())
}
/// Prepare the CLI host for a one-shot in-process command without booting a
/// runtime or installing the server's storage-backed session store.
///
/// Config loading depends on the TinyHumans enricher and persistent hosts need
/// the encrypted-file secret backend installed before a report reads config.
#[cfg(feature = "server")]
pub fn prepare_cli_host() {
openhuman_tinyhumans::register_hooks();
prepare_cli_environment();
}
/// Build a side-effect-limited runtime for the CLI's one-shot doctor command.
///
/// The effective desktop config is selected before the core boots. The normal
/// doctor RPC then runs through `CoreRuntime::invoke`, preserving the shared
/// report path and context-scoped TinyHumans checks. An invalid explicit
/// profile uses a safe in-memory config pinned to the root so the RPC can
/// return its single `profile/exists` finding without loading ambient config.
#[cfg(feature = "server")]
pub async fn doctor_runtime(
requested_profile: Option<&str>,
) -> anyhow::Result<openhuman_tinyhumans::embed::Runtime> {
prepare_cli_host();
let root = crate::embed::config::default_root_openhuman_dir()?;
let config = match crate::core_host::doctor::profile::resolve_desktop_profile_for_doctor(
&root,
requested_profile,
)
.await
{
Ok(selection) => selection.config,
Err(_) if requested_profile.is_some() => doctor_fallback_config(&root),
Err(error) => anyhow::bail!("doctor profile selection failed: {}", error.message()),
};
Ok(doctor_builder(config).build().await?)
}
#[cfg(feature = "server")]
fn doctor_builder(config: RuntimeConfig) -> RuntimeBuilder {
let bearer = Arc::new(uuid::Uuid::new_v4().simple().to_string());
cli_builder()
.workspace(Workspace::Inherit)
.config_source(ConfigSource::Resolved)
.config(config)
.boot_mode(CoreBootMode::Inspection)
.services(ServiceSet::none())
.token(TokenSource::Fixed(bearer))
}
#[cfg(feature = "server")]
fn doctor_fallback_config(root: &std::path::Path) -> RuntimeConfig {
RuntimeConfig {
config_path: root.join("config.toml"),
workspace_dir: root.join("workspace"),
action_dir: root.join("action"),
..RuntimeConfig::default()
}
}
#[cfg(feature = "server")]
fn prepare_cli_environment() {
// The preflight reads URLs before normal CLI dispatch loads `.env` itself.
if let Err(error) = crate::core_host::core::cli::load_dotenv_for_cli() {
log::warn!(
"[rpc:host] cli: early dotenv load failed ({error}); a host setting supplied only \
in that file will not be seen"
);
}
secret_storage::install();
}
/// Parse the side-effect-free embedding capability command.
#[cfg(any(feature = "server", test))]
fn embed_info(args: &[String]) -> anyhow::Result<Option<crate::embed::RuntimeInfo>> {
if args.first().map(String::as_str) != Some("embed") {
return Ok(None);
}
if !matches!(args.get(1).map(String::as_str), Some("info"))
|| args.iter().skip(2).any(|arg| arg != "--json")
{
anyhow::bail!("usage: openhuman-core embed info [--json]");
}
Ok(Some(crate::embed::RuntimeBuilder::standard().describe()))
}
/// Run the core's command-line dispatcher on `args` (without the binary
/// name) as the `openhuman-core` binary does: connected to the TinyHumans
/// backend, with this crate's server behind `run` / `serve`.
///
/// # Errors
///
/// The transport could not be built, a controller extension was refused, or
/// the dispatched command failed.
#[cfg(feature = "server")]
pub fn cli(args: &[String]) -> anyhow::Result<()> {
// Config reads below (and in the dispatcher) need the enricher.
openhuman_tinyhumans::register_hooks();
if let Some(result) = doctor_cli::try_run(args) {
return result;
}
// Introspection belongs above the core: never introduce a core -> embed dependency.
if let Some(info) = embed_info(args)? {
println!("{}", serde_json::to_string_pretty(&info)?);
return Ok(());
}
log::debug!(
"[rpc:host] cli command={} argc={}",
args.first().map(String::as_str).unwrap_or("<none>"),
args.len()
);
prepare_cli_environment();
let mut builder = cli_builder();
if cli_command_uses_storage(args, |namespace| {
// `subsystems` only renders status; it never touches stored state.
namespace != "subsystems"
&& crate::core_host::core::all::cli_handler_for_namespace(namespace).is_some()
}) {
// A one-shot command reads the same backend the server would: the
// resolved storage URL, opened on the core's storage runtime so the
// backend outlives this call.
let provider = crate::core_host::storage::block_on_anyhow(session_store_for_boot())?;
log::debug!("[rpc:host] cli: storage-backed session store installed");
builder = builder.session_store(provider);
}
builder.run_from_args(args)
}
/// Whether the CLI subcommand in `args` should open the configured storage
/// backend itself, following the dispatcher's own grammar
/// (`core::cli::parse_launch_options` then the subcommand match): only the
/// model/provider launch flags precede the command, and the first other token
/// is the command. `run` / `serve` open storage in their own server boot;
/// help, the moved TUI names and `sentry-test` never touch stored state; a
/// bare namespace only prints help unless it has a domain CLI handler
/// (`has_cli_handler`, e.g. `voice`), which runs. `help` counts only where
/// the dispatcher reads it (the command, the function slot or the slot after
/// it), never as an option value.
#[cfg(feature = "server")]
fn cli_command_uses_storage(args: &[String], has_cli_handler: impl Fn(&str) -> bool) -> bool {
let is_help = |arg: &str| matches!(arg, "-h" | "--help" | "help");
let mut rest = args.iter().map(String::as_str).peekable();
while let Some(arg) = rest.peek().copied() {
match arg {
"--model" | "--model-id" | "-m" | "--provider" | "--provider-id" | "-p" => {
rest.next();
match rest.next() {
// The dispatcher rejects a missing or dash-led value with
// its own error; do not open storage ahead of it.
None => return false,
Some(value) if value.starts_with('-') => return false,
Some(_) => {}
}
}
_ if arg.starts_with("--model=")
|| arg.starts_with("--model-id=")
|| arg.starts_with("--provider=")
|| arg.starts_with("--provider-id=") =>
{
rest.next();
}
_ => break,
}
}
let Some(command) = rest.next() else {
return false;
};
if is_help(command) {
return false;
}
let tail: Vec<&str> = rest.collect();
match command {
"run" | "serve" | "tui" | "chat" | "sentry-test" => false,
"doctor" if matches!(tail.first().copied(), Some("report" | "models")) => false,
// The MCP server speaks stdio when given no function and runs agent
// sessions, so it needs the backend.
"mcp" | "mcp-server" => !tail.iter().any(|a| is_help(a)),
// `call` and `agent` print help when given none, or on a help token
// or flag anywhere in their own tails.
"call" | "agent" => match tail.first() {
None => false,
Some(_) => !tail.iter().any(|a| is_help(a)),
},
// A namespace reads help only in the function slot and the slot
// after it; later `--help` tokens are option values to its parser.
namespace => match tail.as_slice() {
[] => has_cli_handler(namespace),
[function, ..] if is_help(function) => false,
[_, slot, ..] if is_help(slot) => false,
_ => true,
},
}
}
/// What the embedded desktop server binds and how it authenticates.
#[cfg(feature = "server")]
#[derive(Clone)]
pub struct DesktopOptions {
/// Bind host; `None` falls back to `OPENHUMAN_CORE_HOST`, then loopback.
pub host: Option<String>,
/// Preferred port; `None` falls back to `OPENHUMAN_CORE_PORT`, then 7788.
/// A stale listener of our own is taken over; see `server::serve`.
pub port: Option<u16>,
/// Serve Socket.IO alongside HTTP JSON-RPC (default `true`).
pub socketio: bool,
/// The per-launch bearer, handed over in memory. `None` keeps the
/// env-or-file token.
pub rpc_token: Option<Arc<String>>,
}
#[cfg(feature = "server")]
impl Default for DesktopOptions {
fn default() -> Self {
Self {
host: None,
port: None,
socketio: true,
rpc_token: None,
}
}
}
#[cfg(feature = "server")]
impl std::fmt::Debug for DesktopOptions {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
// Never print the bearer.
f.debug_struct("DesktopOptions")
.field("host", &self.host)
.field("port", &self.port)
.field("socketio", &self.socketio)
.field("rpc_token", &self.rpc_token.as_ref().map(|_| "<redacted>"))
.finish()
}
}
/// The desktop host's builder: the `desktop` preset with every background
/// service except the core update poller (Socket.IO per `options`), the
/// in-memory bearer and listener, this
/// crate's server launcher and the `http_host.*` controllers.
#[cfg(feature = "server")]
pub fn desktop_builder(options: &DesktopOptions) -> RuntimeBuilder {
let mut services = ServiceSet::desktop();
services.socketio = options.socketio;
// The shell updates through the Tauri updater; releases publish core
// archives for Linux only, so the core's own poller could only report a
// missing asset here (Sentry TAURI-RUST-122R/122S/13B8/13B9).
services.update_scheduler = false;
let mut builder = RuntimeBuilder::desktop()
.services(services)
.server_launcher(crate::server::cli::launch)
.controller_extension(crate::http_host::extension());
if let Some(token) = options.rpc_token.clone() {
builder = builder.token(TokenSource::Fixed(token));
}
if let Some(host) = options.host.clone() {
builder = builder.listen_host(host);
}
if let Some(port) = options.port {
builder = builder.listen_port(port);
}
builder
}
/// Boot the embedded desktop core and serve it until `shutdown_token` is
/// cancelled: [`desktop_builder`], connected, then [`serve_desktop`].
///
/// # Errors
///
/// The transport or runtime could not be built, or the listener failed.
#[cfg(feature = "server")]
pub async fn desktop(
options: DesktopOptions,
shutdown_token: CancellationToken,
ready_tx: tokio::sync::oneshot::Sender<EmbeddedReadySignal>,
) -> anyhow::Result<()> {
openhuman_tinyhumans::register_hooks();
secret_storage::install();
log::debug!("[rpc:host] desktop options={options:?}");
serve_desktop(desktop_builder(&options), shutdown_token, ready_tx).await
}
/// Connect `builder` and serve it as the embedded desktop core: the session
/// store installed, the runtime built, background services started, the
/// listener bound (taking over a stale listener of our own on the preferred
/// port, else falling back), `ready_tx` signalled with the bound port, and
/// the server run until `shutdown_token` is cancelled.
///
/// # Errors
///
/// The transport or runtime could not be built, or the listener failed.
#[cfg(feature = "server")]
pub async fn serve_desktop(
builder: RuntimeBuilder,
shutdown_token: CancellationToken,
ready_tx: tokio::sync::oneshot::Sender<EmbeddedReadySignal>,
) -> anyhow::Result<()> {
let builder = builder.connect().map_err(|error| {
log::warn!("[rpc:host] desktop: TinyHumans connection failed: {error}");
anyhow::Error::new(error)
})?;
crate::server::shims::build_and_serve(builder, Some(ready_tx), Some(shutdown_token)).await
}
/// The terminal UI's builder: the `tui` preset (every domain, no transport,
/// no background services). [`tui`] adds the storage-backed session store.
#[cfg(feature = "session-store")]
pub fn tui_builder() -> RuntimeBuilder {
RuntimeBuilder::tui()
}
/// Boot the TUI's in-process core, connected. The returned runtime owns the
/// core for the session; `Runtime::core_runtime` hands the TUI its
/// `CoreRuntime`.
///
/// Conversations live in the storage backend the host's configuration names
/// (`OPENHUMAN_STORAGE_URL` / `[storage] url`, else `sqlite:<workspace>/storage`;
/// [`crate::session_store::provider_for_host`]).
///
/// # Errors
///
/// A configured storage URL could not be opened, or the transport or runtime
/// could not be built.
#[cfg(feature = "session-store")]
pub async fn tui() -> anyhow::Result<openhuman_tinyhumans::embed::Runtime> {
openhuman_tinyhumans::register_hooks();
secret_storage::install();
log::debug!("[rpc:host] tui: building connected runtime");
let session_store = session_store_for_boot().await?;
let runtime = tui_builder()
.session_store(session_store)
.build()
.await
.map_err(|error| {
log::warn!("[rpc:host] tui: runtime build failed: {error}");
anyhow::Error::new(error)
})?;
log::info!("[rpc:host] tui: core built (DomainSet::full, ServiceSet::none)");
Ok(runtime)
}
/// The storage-backed session store a host opens *before* its runtime is
/// connected. Opening it loads the config (to resolve `[storage] url`), so the
/// TinyHumans config hooks go in first: without the enricher the load-time
/// migrations cannot tell a managed endpoint from a custom one and would
/// rewrite a legacy managed config.
#[cfg(feature = "session-store")]
async fn session_store_for_boot(
) -> anyhow::Result<std::sync::Arc<dyn tinyagents_session::port::SessionStoreProvider>> {
openhuman_tinyhumans::register_hooks();
crate::session_store::provider_for_host().await
}
#[cfg(test)]
#[path = "host_tests.rs"]
mod tests;