An edge-AI appliance that runs a local agent, its long-term memory, and a desktop control surface as one self-provisioning box.
Table of Contents
agentbox packages a self-hosted AI agent, its persistent memory, and a native desktop front end into a single edge appliance you can provision and hand off. Instead of routing every request to a cloud endpoint, agentbox keeps the agent loop, knowledge store, and access control on the box — useful where data residency, latency, offline operation, or running your own models matter.
It is built as a monorepo of four cooperating parts — the Hermes agent, the gBrain memory layer, the desktop client, and the vendored MailBOX email stack — plus the infrastructure scripts that turn a bare machine into a working appliance.
Important
AgentBOX is the source of truth for the unified appliance = the MailBOX email pipeline (triage → draft → approve → send) plus the Hermes agent + gBrain, co-resident on one Jetson. As of UMB-105 the MailBOX app stack is vendored in this monorepo under mailbox/ (no external clone); install/agentbox-install.sh syncs it into place. This repo owns everything: the vendored stack, the installer, the Hermes/gBrain wiring (config/hermes/), the compose override (config/), the boot units (systemd/), and the JetPack flow.
New box: bare hardware → flash JetPack per docs/flash-jetson.md (NVIDIA ISO installer); already-flashed Jetson → install/onboarding-test-setup.sh (OOBE) or install/agentbox-install.sh --prototype (base). See also docs/agentbox-jp72-reproduction.v0.1.0.md.
---
title: agentbox
---
flowchart TB
subgraph BOX["agentbox appliance"]
DESK["hermes-desktop<br/>(TypeScript UI)"]
AGENT["hermes-agent<br/>(Python agent loop)"]
BRAIN["gBrain<br/>(memory / knowledge store)"]
ACL["infra/acl<br/>(access control)"]
end
USER([Operator]) --> DESK
DESK <--> AGENT
AGENT <--> BRAIN
AGENT --> ACL
AGENT -. optional .-> EXT[(External tools / models)]
PROV["provisioning + bin/"] -.bootstraps.-> BOX
| Component | Path | Stack | Role |
|---|---|---|---|
| Hermes agent | upstream, installed on-box | Python | Upstream NousResearch hermes-agent v0.18.2 (v2026.7.7.2) at ~/.hermes/hermes-agent-v2; patch branch agentbox2-v3 in UMB-Advisors/agentbox-hermes-patches (= upstream + one /dashboard proxy patch). Served at /hermes/ behind the sidecar. |
| Custom UI + features | UMB-Advisors/agentbox-sidecar |
Python / TypeScript | ALL custom AgentBOX features + the operator dashboard (FastAPI :9200, serves the dashboard at /, stock hermes at /hermes/). |
| gBrain | gbrain-master/ |
Python | Persistent memory and knowledge store the agent reads from and writes to. |
| Desktop | hermes-desktop-main/ |
TypeScript | Native control surface for interacting with and supervising the agent. |
| ACL | infra/acl/ |
Config | Access control for agent capabilities and resources. |
| Provisioning | provisioning/ |
Shell | Scripts that turn a bare machine into a configured appliance. |
| Unified installer | install/ + config/ + systemd/ |
Shell | One-command bring-up of the unified MailBOX + Hermes appliance; clones the MailBOX stack and wires Hermes/gBrain/boot. |
| MailBOX stack | mailbox/ |
Compose | Email pipeline (postgres, qdrant, ollama, n8n, dashboard). Vendored in this monorepo (UMB-105); install/agentbox-install.sh syncs it into place. |
| CLI | bin/ |
Shell | Entry-point commands for operating the box. |
| Skill | .skill/ |
— | Packaged skill definition for agent tooling. |
| Docs | docs/ |
TeX / Markdown | Design notes and appliance documentation. |
Important
agentbox targets a Linux host (developed on Ubuntu 24.04). You will need Python 3.11+, Node.js 20+, and a POSIX shell. Component subprojects carry their own dependency manifests.
git clone https://github.com/UMB-Advisors/AgentBOX.git
cd AgentBOXThe real bring-up flow:
- Flash the Jetson — from scratch, use NVIDIA's ISO installer per
docs/flash-jetson.md(write the JetPack 7.2 installer to USB with Etcher → boot → install to NVMe → first-boot setup). Host-driven flashing (/agentbox-flashskill, or the SDK-Manager reflash runbook below) is an advanced alternative. - Install on the box:
install/agentbox-install.sh --prototype—⚠️ STAGES 7/7.5/7.6 currently provision the pre-sidecar architecture; the installer rework is tracked under MBOX-428. See the warning header in the script. - Sidecar setup: install
UMB-Advisors/agentbox-sidecar(agentbox-sidecar.service,:9200) per itsdocs/update-runbook.md— this is the user-facing UI and the home of all custom features.
To stand up agentbox on fresh hardware rather than running the components by hand, run
install/agentbox-install.sh from the repo root on the target machine (staged, idempotent;
see step 2 above for the pre-sidecar caveat).
Tip
Provisioning wires up the agent, gBrain, the ACL layer, and the boot units into a single managed appliance. Review infra/acl/ before exposing the box on a shared network.
Provisioning assumes a flashed JetPack base (JetPack 7.2 — Jetson Linux r39.2, Ubuntu 24.04, CUDA 13).
From scratch (recommended): NVIDIA's ISO installer — no host PC, no recovery-mode jumper, no BSP. You need the kit + its 19 V supply, a laptop, a USB stick (16 GB+), and an NVMe SSD (recommended over microSD — the install pulls models + Docker images). Follow NVIDIA's Orin Nano quick start; the short version:
- Confirm the board's UEFI/QSPI firmware is 36.0+ (power on with a monitor, press Esc at the splash to read the version; if older, do NVIDIA's JetPack-6 firmware update first).
- Download the Jetson installer ISO (JetPack 7.2 / r39.2) from the JetPack download page.
- Write the ISO to the USB stick with Balena Etcher (you can't just copy the file — it must be bootable media).
- Install the NVMe SSD, connect a monitor + keyboard, insert the USB, and plug in the 19 V supply (it powers on automatically).
- Boot from USB: press Esc at the splash → Boot Manager → the USB disk.
⚠️ Confirm the QSPI capsule update — pressY(the prompt times out in ~30 s; miss it and the install fails later). It runs two passes and may reboot between them — let it finish.- At GRUB choose Install Jetson ISO r39.2, select the NVMe as the target, confirm (this erases it), let it finish, and reboot.
- Remove the USB, boot from NVMe, and complete first-boot
oem-config(EULA, language, network, create your user + hostname).
Then, before provisioning: set MAXN SUPER (power-mode indicator → the box defaults to 25 W), enable SSH (sudo apt update && sudo apt install -y openssh-server), and get the box on your network. Provisioning reaches it over SSH as the user you created.
➡️ Full guide (AgentBOX specifics + what to run next): docs/flash-jetson.md.
Advanced / headless re-image (host-driven): Force Recovery + sdkmanager --cli from a host — useful for scripted or remote re-imaging of an existing box:
➡️ docs/reflash-jetpack-7.2.v0.1.0.md — backup → Force Recovery → sdkmanager --cli flash → headless (no desktop) → restore.
Warning
A reflash wipes the NVMe (root, Docker volumes, Tailscale state, users). Back up off‑box first, and note that the JetPack 6.2→7.2 jump (CUDA 12.6→13) requires rebuilding the GPU containers and updating the provisioning/ pins. See the runbook's caveats.
agentbox/
├── bin/ # CLI entry points
├── docs/ # design notes & documentation
├── gbrain-master/ # gBrain — persistent memory / knowledge store
├── hermes-desktop-main/ # desktop control surface
├── infra/acl/ # access control
├── provisioning/ # appliance bootstrap scripts
└── .skill/ # packaged skill definition
agentbox is part of the thUMBox appliance family from UMB Advisors — a line of edge-AI boxes that put agents, memory, and control on hardware you own.
Issues and pull requests are welcome. Please:
- Open an issue describing the change before large PRs.
- Keep component changes scoped to their subproject (
hermes-agent,gbrain,hermes-desktop). - Run each component's checks before submitting.
Proprietary — internal UMB Advisors appliance monorepo; no open-source license granted. (A LICENSE file is intentionally absent.)
Built by UMB Advisors · part of the thUMBox appliance family