EdgeCitadel

EdgeCitadel connects AI Agents across a Core and enrolled Edge hosts. It runs complete Agents from packages such as Gemma and Home Assistant adapters, and connects active Pi, Claude Code, and Codex sessions through their native plugin systems.

Install

Install uv if it is not already available, then install EdgeCitadel as an isolated CLI tool:

uv tool install edgecitadel

On macOS, Homebrew is also supported through the EdgeCitadel tap:

brew tap EdgeCitadelTeam/edgecitadel
brew trust --tap EdgeCitadelTeam/edgecitadel
brew install edgecitadel

Homebrew 6 requires the trust step before loading formulas from a non-official tap.

uv tool install avoids modifying an operating-system-managed Python environment. See the Python distribution guide for a manual virtual-environment fallback.

Then run the guided, idempotent installer from the project where host-local Plugins should be configured:

edgecitadel install

The terminal guide first asks whether this host should join an existing Core or create a new one. It then offers local-only, Tailscale, or custom-address Core access, or collects an invitation, explains the Edge messaging choices, detects available native agent hosts, and shows the exact Plugin installation plan before asking for confirmation.

For automation, make every choice explicit, for example edgecitadel install --create --network tailscale --plugin codex --scope user --yes on a Core.

Create a Core

For normal setup, run edgecitadel install and choose create. The guide asks how the server should be reached. All three choices start the Core on this computer. edgecitadel create offers the same guide when only the server is needed.

For unattended setup, start Docker and provide every choice as flags:

edgecitadel install --create --network tailscale --plugin codex --scope user --yes
edgecitadel doctor

The unified command creates the Core, starts its services, installs the selected Plugin, checks local requirements, and prints the dashboard URL.

Use --network local for loopback-only access. For an operator-protected custom network, use --network custom --host core.example.internal --bind-address <assigned-ip>. Docker Engine 28+ and Compose 2.24.4+ are required for managed access policy. See onboarding for reruns, address validation, network boundaries, and compatibility with earlier deployments.

Join an Edge

Create a one-time invitation on the Core:

edgecitadel invite --node-id studio-macmini

Copy the returned invitation URI to the Edge. The default single-client mode connects the EdgeCitadel service directly to Core NATS:

edgecitadel install --join 'ecjoin://...' --plugin codex --scope user --yes

Use nats_leaf when Agents on this host must keep communicating while the Core connection is unavailable:

edgecitadel install --join 'ecjoin://...' --messaging-mode nats_leaf --plugin codex --scope user --yes

The unified commands enroll the Edge, start its EdgeCitadel services and any mode-specific NATS process, and install the selected native-host Plugin. Use the lower-level edgecitadel join command only when those remaining steps will be managed separately.

In both modes, Agent integrations talk to the host-local EdgeCitadel service. Only nats_leaf needs a local NATS server; it is the durable local message bus and maintains the outbound Leaf connection to Core. If nats-server is not already on PATH, EdgeCitadel downloads its pinned, SHA-256-verified NATS release into ~/.edgecitadel/runtime/nats-server. A custom executable can be selected with EDGECITADEL_NATS_SERVER.

Install an Agent Package

Agent Packages contain complete runtimes operated by EdgeCitadel. An installed runtime may declare one or more Agent identities:

edgecitadel agent install gemma
edgecitadel agent list
edgecitadel agent status edgecitadel.gemma

Home Assistant is installed the same way after its URL, token, and allowlist are configured. EdgeCitadel operates the adapter and never installs or removes Home Assistant itself. See the Gemma guide and Home Assistant guide.

Connect an existing Agent

Plugins add Agent discovery, delegation, inbox, task-state, trace, and diagnostic tools to an active host session. They do not start the host in the background, and EdgeCitadel does not pass NATS credentials through the plugin protocol.

edgecitadel plugin install codex
edgecitadel plugin install claude-code --scope project
edgecitadel plugin install pi --scope user
edgecitadel plugin list

Each command delegates to the host's native package manager and reports package installation separately from activation. Start a new host session, then use its edgecitadel_* tools. Inspect active sessions with edgecitadel connector list and edgecitadel connector status <connector-id>. The unified installer repairs a selected Plugin whose distribution path moved; use edgecitadel plugin repair <host> to perform that repair explicitly.

Operate

edgecitadel status
edgecitadel doctor
edgecitadel service status
edgecitadel task list --connector-id <connector-id>
edgecitadel trace list --connector-id <connector-id>

Stop a Core without deleting its data with edgecitadel down.

Upgrade or uninstall

Use the package manager that installed EdgeCitadel:

uv tool upgrade edgecitadel
uv tool uninstall edgecitadel

brew upgrade edgecitadel
brew uninstall edgecitadel

Before uninstalling an Edge, run edgecitadel service stop; in nats_leaf mode also run edgecitadel messaging stop. Uninstall preserves local state in ~/.edgecitadel.

More detail: onboarding and troubleshooting and contributing.

License

MIT