GAIA Personal Setup

Customer-facing installer for running one or more private AI assistants on your computer as Docker containers.

Powered by open-source Hermes Agent (Nous Research).
This product is not part of the Hermes upstream repo and is not an official Nous product.

What customers get

• Install multiple assistants side by side (work / personal / family)
• Each assistant = one Docker container + one private data folder
• Choose folders on the PC each assistant may read (or write)
• Own LLM API key (BYOK) and own Telegram/Discord bot
• Local dashboard per assistant (http://<assistant>.localhost:…)

Your PC
├── GAIA-Personal/
│   ├── instances.json
│   └── instances/
│         ├── work/          → container gaia-personal-work
│         └── home/          → container gaia-personal-home
│
├── ~/Documents/Projects  ──mounted──▶  /mnt/gaia/projects  (ro/rw)
└── ~/Downloads           ──mounted──▶  /mnt/gaia/downloads

Prerequisites

1. Docker Desktop (Windows/Mac) or Docker Engine (Linux)
2. Internet (pull image + call your LLM provider)
3. ~2 GB free RAM per assistant (cloud models)

User guide

Open the HTML guide here:

docs/user-guide.html

It covers install, Docker, the setup wizard, folder access, upgrades, backups, and troubleshooting.

Need help installing?

If you need help using this installer, I can help: https://www.donvitocodes.com/gaia

Hermes for Personal AI — software installation (2 hrs)
Hands-on session: I'll guide you through installing Hermes Agent on your computer, or using this GAIA multiple-instances installer.

Quick start (non-technical)

1. Install Docker Desktop and start it.
2. Open the GAIA setup folder.
3. Double-click:
   • Mac: Start GAIA Personal Setup.command
   • Windows: Start GAIA Personal Setup.bat (or gaia-setup-personal.exe)
4. Browser opens http://127.0.0.1:8788 — keep the small window open.

Brand: donvitocodes.com

Quick start (developers)

cd gaia-setup-personal
go build -o bin/gaia-setup-personal ./cmd/gaia-setup-personal

./bin/gaia-setup-personal doctor
./bin/gaia-setup-personal init
./bin/gaia-setup-personal wizard    # or just: ./bin/gaia-setup-personal

No-args / double-click defaults to the setup wizard.

CLI with folder mounts

./bin/gaia-setup-personal provision \
  --id work \
  --name "Work assistant" \
  --openrouter-key "sk-or-..." \
  --telegram-token "123:ABC" \
  --dashboard-pass "longpassword1" \
  --folder ~/Documents/Work:ro \
  --folder ~/Downloads:rw

./bin/gaia-setup-personal list
./bin/gaia-setup-personal folders work
./bin/gaia-setup-personal open work

:ro = read-only (default if you omit suffix and leave default).
:rw = read-write.

JSON payload

See examples/wizard.sample.json — includes a folders array:

"folders": [
  { "hostPath": "~/Documents/Projects", "readOnly": true, "label": "Projects" },
  { "hostPath": "~/Downloads", "readOnly": false, "label": "Downloads" }
]

Folder access model

Mount	Purpose
instances/<id> → /opt/data	Private Hermes home (always)
Customer folders → /mnt/gaia/<label>	Optional; you pick per assistant

Safety defaults

• UI defaults new folders to read-only
• Refuses mounting /, /etc, docker.sock, etc.
• Containers bind dashboard/API to 127.0.0.1 only
• Default ports:
  • macOS/Linux: dashboard starts at 9121, API starts at 8643
  • Windows: dashboard starts at 19121, API starts at 18643
• Before assigning a port, GAIA skips:
  • ports already used by other GAIA assistants
  • active local listeners
  • Windows TCP excluded ranges reserved by WSL2/Hyper-V/WinNAT (netsh interface ipv4/ipv6 show excludedportrange protocol=tcp)
• Browser links use per-assistant hostnames like http://aorus.localhost:19121 so multiple Hermes dashboards can stay logged in at the same time
• Changing folders later requires recreate (destroy + provision)

Upgrade path

# Upgrade all assistants (backup instance data first, then pull + recreate)
./bin/gaia-setup-personal update

# One assistant
./bin/gaia-setup-personal update work

# Pin Hermes version
./bin/gaia-setup-personal update --image nousresearch/hermes-agent:v1.2.3
# or
export GAIA_HERMES_IMAGE=nousresearch/hermes-agent:v1.2.3

# Also copy user folder mount *files* into backup (can be large)
./bin/gaia-setup-personal update --backup-mounts

# List backups
./bin/gaia-setup-personal backups
./bin/gaia-setup-personal backups work

What update does

1. Backup under ~/GAIA-Personal/backups/<id>/<timestamp>/
   • instance-data/ — Hermes private data (always)
   • instances.json + instance.json — manifest snapshot
   • mounts.json — list of user folder paths
   • mounts/ — optional full file copy (--backup-mounts)
2. docker pull image (unless --skip-pull)
3. Recreate container with same data dir, ports, and folder mounts
4. Dashboard password kept via gaia-runtime.json in the instance folder (chmod 600)

API (local wizard server): POST /api/update with optional {"id":"work"}.

Upgrade the installer app

Replace the gaia-setup-personal binary / release bundle; data home stays ~/GAIA-Personal.

Commands

Command	Description
doctor	Docker + paths
init	Create ~/GAIA-Personal
wizard	End-user UI on loopback 8788
provision	Create assistant + mounts
update [id]	Backup + upgrade engine
backups [id]	List upgrade backups
list	All assistants
folders <id>	Show mounts
start / stop / destroy / open	Lifecycle

Data location

• Default home: ~/GAIA-Personal (override GAIA_HOME or GAIA_PERSONAL_HOME)
• Windows: %USERPROFILE%\GAIA-Personal

Releases (GitHub + website)

See docs/RELEASING.md.

git tag v0.2.1
git push origin v0.2.1

GitHub Actions builds Mac / Windows / Linux zip bundles and publishes a Release. Link those assets from donvitocodes.com.

Relationship to other repos

Repo	Role
gaia-setup	Internal/operator-oriented scaffold
gaia-setup-personal	What you ship to end users
hermes-agent (Nous)	Engine image only — docker pull

License

MIT for this installer. Hermes Agent remains separately licensed by Nous Research.