//! `hivectl` — operator-facing host CLI for hyperhive. //! //! Sibling binary to the `hive-c0re` daemon. Where `hive-c0re`'s //! subcommands focus on the broker / approval / topology surface //! (`spawn`, `kill`, `rebuild`, `approve` …), `hivectl` covers //! host-side administration — both manual provisioning operations //! that work without the daemon running (forge, matrix, gateway) AND //! daemon-assisted agent management (agents restart/restart-all) that //! goes through the host admin socket. //! //! Verbs read configuration off the same on-disk paths c0re uses //! (`/var/lib/hyperhive/forge-core-token`, //! `/var/lib/hyperhive/matrix-register-token`, per-agent state //! dirs) and reuse the `forge` / `matrix` modules from the //! `hive-c0re` lib — single source of truth, no duplication. #[cfg(unix)] use std::os::unix::process::CommandExt as _; use std::path::{Path, PathBuf}; use anyhow::{Context as _, Result, bail}; use clap::{Args, Parser, Subcommand}; use hive_c0re::coordinator::Coordinator; #[derive(Parser)] #[command( name = "hivectl", about = "hyperhive host CLI — operator-facing administration", long_about = "\ Sibling to the `hive-c0re` daemon binary. Covers host-side admin \ operations that don't go through the broker — manual user \ provisioning on the bundled forge + matrix containers, plus future \ recovery / debugging verbs.\ " )] struct Cli { #[command(subcommand)] cmd: Cmd, } #[derive(Subcommand)] enum Cmd { /// Forgejo user provisioning. Manual entry point to the same /// idempotent flow c0re runs automatically at boot /// (`forge::ensure_all`) — useful for recovery, ad-hoc reprovisioning, /// or single-agent fixes without bouncing the daemon. Forge { #[command(subcommand)] cmd: ForgeCmd, }, /// matrix-tuwunel user provisioning. Manual entry point to the same /// idempotent flow c0re runs automatically at boot /// (`matrix::ensure_all`) — useful when the boot-time sweep skipped /// an agent (e.g. matrix container wasn't up yet) or to re-register /// after wiping a token file. Matrix { #[command(subcommand)] cmd: MatrixCmd, }, /// Gateway htpasswd user management. Add, remove, or list users in /// an htpasswd file used by the gateway's HTTP Basic auth /// (`services.hyperhive.gateway.auth`). Credentials are stored as /// `BCrypt` hashes — no extra service or PAM required. Gateway { #[command(subcommand)] cmd: GatewayCmd, }, /// Agent container management. Requires the hive-c0re daemon to be /// running (connects to the host admin socket). Agents { #[command(subcommand)] cmd: AgentsCmd, }, /// Open an interactive Claude session inside an agent container. /// /// Replaces the current process with `machinectl shell /// @h-` running `claude --continue` from the agent's /// state dir — drops the operator straight into the agent's live /// Claude session with its full loaded context and persona. Requires /// root (same as all machinectl shell operations) and the container /// must be running. /// /// To match the harness exactly, choom enters **as the agent user** /// (not root) so claude reads the OAuth credentials from the agent's /// `/home//.claude`; runs from the agent's state dir /// (`/agents//state`) so `--continue` resumes the right /// per-project session and `CLAUDE.md` loads; and passes the same /// `--settings` / `--mcp-config` / `--system-prompt-file` the harness /// writes to `/run/hive-config/` (settings, MCP tools, role prompt). /// Entering as root (the `machinectl shell` default) loses all of it. /// /// Pass `--fresh` to start a new Claude session instead of continuing /// the most recent one. Choom { /// Agent name (e.g. `damocles`, `iris`). name: String, /// Start a fresh Claude session instead of continuing the most /// recent one. Without this flag `--continue` is passed to Claude /// so the operator joins the agent's ongoing session context. #[arg(long)] fresh: bool, }, /// Stop containers hive-wide in one operator action. Bare `hivectl /// stop` stops **everything** — all sub-agents plus the ci, forge, /// gateway, and matrix infra containers. Narrow it with scope flags: /// `--agents` (all sub-agents), `--ci` / `--forge` / `--gateway` / /// `--matrix` (named infra), and `--agent ` (repeatable) for /// specific sub-agents. Flags are additive (e.g. `--agents --matrix`). /// Requires the hive-c0re daemon (connects to the host admin socket). /// hive-c0re itself is never stopped — it services the request. Stop { #[command(flatten)] scope: ScopeArgs, /// Gracefully quiesce each agent (finish the current turn, drain /// the inbox) before stopping, instead of a hard stop. /// /// NOTE: not yet effective — the per-agent quiesce is still being /// implemented (see the graceful-agent-stop tracker), so today /// this falls through to a hard stop. The flag is accepted now so /// the wire/CLI shape is stable when the quiesce lands. #[arg(long)] graceful: bool, /// Path to the hive-c0re host admin socket. #[arg(long, default_value = DEFAULT_HOST_SOCKET)] socket: PathBuf, }, /// Start containers hive-wide — the inverse of `hivectl stop`. Bare /// `hivectl start` starts everything back up; the same scope flags as /// `stop` narrow it (`--agents`, `--ci`, `--forge`, `--gateway`, /// `--matrix`, `--agent `). Requires the hive-c0re daemon. Start { #[command(flatten)] scope: ScopeArgs, /// Path to the hive-c0re host admin socket. #[arg(long, default_value = DEFAULT_HOST_SOCKET)] socket: PathBuf, }, /// Emit the full CLI reference as `CommonMark` to stdout. /// /// Hidden tooling command (not part of day-to-day operator admin): /// walks this binary's own clap command tree and renders every verb, /// flag, and help string as markdown. Used by the docs build to keep /// the published `hivectl` reference in lockstep with the code — no /// hand-maintained command list to drift out of date. #[command(hide = true)] MarkdownDocs, } /// Shared scope flags for `hivectl stop` / `hivectl start`. With no flag /// set the verb targets **everything** (all sub-agents + every controllable /// infra container). Setting any flag restricts to the selected classes, /// additively. // One bool per selectable container class, each mapping 1:1 to a clap flag; // orthogonal toggles, not a state machine — hence the bools allow (mirrors // `hive_sh4re::LifecycleScope`). #[allow(clippy::struct_excessive_bools)] #[derive(Args)] struct ScopeArgs { /// All sub-agent containers. #[arg(long)] agents: bool, /// A specific sub-agent by name. Repeatable: `--agent a --agent b`. #[arg(long = "agent", value_name = "NAME")] agent: Vec, /// The CI runner container (`hive-ci`). #[arg(long)] ci: bool, /// The forge container (`hive-forge`). #[arg(long)] forge: bool, /// The gateway container (`hive-gateway`). #[arg(long)] gateway: bool, /// The matrix container (`hive-matrix`). #[arg(long)] matrix: bool, } impl ScopeArgs { fn to_scope(&self) -> hive_sh4re::LifecycleScope { hive_sh4re::LifecycleScope { agents: self.agents, agent_names: self.agent.clone(), ci: self.ci, forge: self.forge, gateway: self.gateway, matrix: self.matrix, } } } #[derive(Subcommand)] enum ForgeCmd { /// Create or refresh the Forgejo account + token for ``. /// /// When `` matches an existing agent (i.e. it has a state /// dir under `/var/lib/hyperhive/agents/`), persists the token to /// `/forge-token` (idempotent: re-mints + rewrites every /// call so the on-disk scope matches the current /// `forge::TOKEN_SCOPES`). /// /// When `` is **not** an agent (a human or any other /// non-container account), creates the forgejo user and prints the /// freshly-minted token to stdout — no `/var/lib/hyperhive/agents/` /// directory is created for the user. /// /// Without `--password` / `--password-stdin` a random throwaway is /// used (fine for agents — they auth by token via tea / hive-forge). /// Set a password to log into the forge web UI afterwards. /// `--password` is idempotent: re-running with the same value sets /// the same password (covers password resets on already-created /// accounts since `forgejo admin user create` silently no-ops once /// the user exists). CreateUser { /// Forgejo username. For agents: the container/agent name /// (`` in `h-`; manager uses the literal `manager`). /// For humans: any forgejo username — `mara`, `damocles`, etc. name: String, /// Set the account password to this string instead of a random /// throwaway. Use this for operator accounts that need to log /// into the forge web UI. Mutually exclusive with /// `--password-stdin`. WARNING: the password is visible in /// shell history + process listings; prefer `--password-stdin` /// for anything sensitive. #[arg(long)] password: Option, /// Read the password from stdin (single line, trailing newline /// stripped) instead of an inline flag. Mutually exclusive with /// `--password`. #[arg(long, conflicts_with = "password")] password_stdin: bool, }, } #[derive(Subcommand)] enum MatrixCmd { /// Create or refresh the matrix account + access token for ``. /// /// When `` matches an existing agent (i.e. it has a state /// dir under `/var/lib/hyperhive/agents/`), persists the token to /// `/matrix-token`. Skips registration when the file is /// already populated; delete it to force re-registration. /// /// When `` is **not** an agent (a human or any other /// non-container account), registers the matrix user and prints /// the freshly-minted access token to stdout — no /// `/var/lib/hyperhive/agents/` directory is created for the user. /// /// Without `--password` / `--password-stdin` a random throwaway is /// used (fine for agents — they auth by `access_token`, never by /// password). Set a password to log into a matrix web client /// afterwards. CreateUser { /// Matrix localpart. For agents: the container/agent name. /// For humans: any matrix localpart — `mara`, `damocles`, etc. name: String, /// Set the account password to this string instead of a random /// throwaway. Use this for operator accounts that need to log /// into matrix web clients via `m.login.password`. Mutually /// exclusive with `--password-stdin`. WARNING: the /// password is visible in shell history + process listings; /// prefer `--password-stdin` for anything sensitive. #[arg(long)] password: Option, /// Read the password from stdin (single line, trailing newline /// stripped) instead of an inline flag. Mutually exclusive with /// `--password`. #[arg(long, conflicts_with = "password")] password_stdin: bool, }, /// Provision (or re-provision) the hive system admin matrix account /// (`@hive:`). hive-c0re runs this automatically on startup /// before the agent sweep so the account is the first registered /// user — Conduit/tuwunel grants admin rights to the first user. /// Run manually to recover a missing admin token file. SyncAdmin, /// Promote a matrix user to homeserver admin via the admin API. /// Uses the hive system admin token at /// `/var/lib/hyperhive/matrix/admin-token`. The `server_name` is /// discovered automatically from the running homeserver. PromoteUser { /// Matrix localpart of the user to promote (e.g. `argus`). name: String, }, /// Reset a matrix user's password via the admin API and persist the /// new password to `/var/lib/hyperhive/matrix/creds/-password` /// so the next `ensure_user_for` (or `create-user`) can re-login. /// /// After this command succeeds, run `hivectl matrix create-user /// ` to mint a fresh access token for the agent. ResetPassword { /// Matrix localpart of the account to reset (e.g. `argus`). name: String, }, /// Invite a matrix user to the hive Space (default) or a specific /// room. Uses the hive admin token; the admin account must be a /// member of the target room with invite power (it owns the hive /// Space). Idempotent — already-member / already-invited is a no-op. Invite { /// User to invite: a full id (`@mara:server`) or a bare /// localpart (qualified with the homeserver's `server_name`). user: String, /// Target room id (`!abc:server`) or alias (`#name:server`). /// Omit to invite to the hive Space. #[arg(long)] room: Option, }, } /// Default htpasswd file path — the host-side location of the gateway's /// credential store, pre-created by a tmpfiles rule when /// `services.hyperhive.gateway.auth.enable = true`. const DEFAULT_HTPASSWD_FILE: &str = "/var/lib/hyperhive/gateway/gateway.htpasswd"; #[derive(Subcommand)] enum GatewayCmd { /// Add a new user or update the password of an existing user in the /// gateway htpasswd file. The password is hashed with `BCrypt` (cost 12). /// /// Pass `--password-stdin` when scripting or when you don't want the /// password visible in shell history. The file is created if it does /// not exist; its parent directory must already exist. CreateUser { /// Username to add or update. username: String, /// Set the password inline. WARNING: visible in shell history and /// process listings — prefer `--password-stdin` for sensitive input. /// Mutually exclusive with `--password-stdin`. #[arg(long, conflicts_with = "password_stdin")] password: Option, /// Read the password from stdin (single line, trailing newline /// stripped). Mutually exclusive with `--password`. #[arg(long)] password_stdin: bool, /// Path to the htpasswd file. Defaults to the standard gateway /// credential store at `/var/lib/hyperhive/gateway/gateway.htpasswd`. #[arg(long, short = 'f', default_value = DEFAULT_HTPASSWD_FILE)] file: PathBuf, }, /// Remove a user from the gateway htpasswd file. Exits with an error /// when the user is not found so callers can detect the no-op case. DeleteUser { /// Username to remove. username: String, /// Path to the htpasswd file. Defaults to the standard gateway /// credential store. #[arg(long, short = 'f', default_value = DEFAULT_HTPASSWD_FILE)] file: PathBuf, }, /// List all usernames in the gateway htpasswd file, one per line. ListUsers { /// Path to the htpasswd file. Defaults to the standard gateway /// credential store. #[arg(long, short = 'f', default_value = DEFAULT_HTPASSWD_FILE)] file: PathBuf, }, } /// Default host admin socket path. Must match `hive-c0re`'s default in /// `main.rs` (`/run/hyperhive/host.sock`) — the daemon binds there and /// `hivectl agents` connects to it. const DEFAULT_HOST_SOCKET: &str = "/run/hyperhive/host.sock"; #[derive(Subcommand)] enum AgentsCmd { /// Stop and start a single agent container without rebuilding config. /// Useful for "kick the container" when the process is stuck or the /// container needs a clean restart without changing the NixOS config. Restart { /// Agent name (e.g. `damocles`, `ruth`). name: String, /// Path to the hive-c0re host admin socket. #[arg(long, default_value = DEFAULT_HOST_SOCKET)] socket: PathBuf, }, /// Stop and restart ALL managed agent containers in sequence. /// Iterates the live container list and restarts each one. Any per-agent /// failure is reported at the end rather than stopping mid-run, so all /// containers get a restart attempt. RestartAll { /// Path to the hive-c0re host admin socket. #[arg(long, default_value = DEFAULT_HOST_SOCKET)] socket: PathBuf, }, } #[tokio::main] async fn main() -> Result<()> { tracing_subscriber::fmt() .with_env_filter( tracing_subscriber::EnvFilter::try_from_default_env() .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("info")), ) .init(); let cli = Cli::parse(); match cli.cmd { Cmd::Forge { cmd } => match cmd { ForgeCmd::CreateUser { name, password, password_stdin, } => forge_create_user(&name, password.as_deref(), password_stdin).await, }, Cmd::Matrix { cmd } => match cmd { MatrixCmd::CreateUser { name, password, password_stdin, } => matrix_create_user(&name, password.as_deref(), password_stdin).await, MatrixCmd::SyncAdmin => matrix_sync_admin().await, MatrixCmd::PromoteUser { name } => matrix_promote_user(&name).await, MatrixCmd::ResetPassword { name } => matrix_reset_password(&name).await, MatrixCmd::Invite { user, room } => matrix_invite(&user, room.as_deref()).await, }, Cmd::Gateway { cmd } => match cmd { GatewayCmd::CreateUser { file, username, password, password_stdin, } => gateway_create_user(&file, &username, password.as_deref(), password_stdin), GatewayCmd::DeleteUser { file, username } => gateway_delete_user(&file, &username), GatewayCmd::ListUsers { file } => gateway_list_users(&file), }, Cmd::Agents { cmd } => match cmd { AgentsCmd::Restart { name, socket } => agents_restart(&socket, &name).await, AgentsCmd::RestartAll { socket } => agents_restart_all(&socket).await, }, Cmd::Stop { scope, graceful, socket, } => stop(&socket, scope.to_scope(), graceful).await, Cmd::Start { scope, socket } => start(&socket, scope.to_scope()).await, Cmd::Choom { name, fresh } => choom(&name, fresh), Cmd::MarkdownDocs => { print!("{}", clap_markdown::help_markdown::()); Ok(()) } } } /// True when `name` matches an existing hyperhive agent — i.e. it has a /// persistent state dir under `/var/lib/hyperhive/agents/`. We use the /// state dir (not the live container list) so kept-state tombstones /// still resolve as agents — re-provisioning a destroyed-but-kept agent /// should still drop its token in the existing state tree. fn is_agent(name: &str) -> bool { Coordinator::agent_state_root(name).exists() } /// Drop into an interactive Claude session in the agent container. /// /// Replaces the current process (exec) with `machinectl shell /// @h- /bin/sh -lc '