clawdie-ai/docs/public/reference/multi-agent.md

title
Multi-Agent Deployment (Optional)

Clawdie supports running multiple independent agents on the same FreeBSD host, but the default path is one agent per host or per bhyve VM. Use this guide only when you intentionally want a second agent later.

Quick decision

• Easiest isolation: one agent per bhyve VM (each VM has its own warden0)
• Same-host multi-agent: one host warden0 bridge carries multiple /24 subnets

Concepts (what must stay unique)

• AGENT_NAME is the identity key:
  • rc.d service name (/usr/local/etc/rc.d/${AGENT_NAME})
  • tmux session name
  • jail name prefix (recommended)
  • DB identifiers (users + databases)
• AGENT_SUBNET_BASE assigns a dedicated /24 to that agent:
  • pick any private /24 that does not collide with another agent
  • repo examples below use 10.0.1
  • live installs can also use 192.168.72, 172.16.50, etc
  • you can also use 172.16.50, 192.168.100, etc — pick any private /24 and stay consistent
• warden0 is the canonical bridge name. A single warden0 can host multiple subnets; the host must own the .1 gateway IP for each subnet.
• Prefer VNET jails (bastille create -B ... warden0) for cleaner isolation.

Same-host multi-agent (VNET path)

Example: add a second agent named atlas on 10.0.1.0/24.

1) Create a second project directory

Use a separate clone so each agent has its own .env, logs/, and runtime state.

2) Configure .env for the second agent

Minimum keys to set (example values):

AGENT_NAME=atlas
ASSISTANT_NAME=Atlas

AGENT_SUBNET_BASE=10.0.1
WARDEN_GATEWAY=10.0.1.1
WARDEN_SUBNET=10.0.1.0/24

WARDEN_GIT_IP=10.0.1.2
WARDEN_CMS_IP=10.0.1.3
WARDEN_OLLAMA_IP=10.0.1.4
WARDEN_LLAMA_CPP_IP=10.0.1.4
WARDEN_DB_IP=10.0.1.5

These are example values only. If your host already uses another private subnet, keep that and stay consistent across the rest of the file.

Jail name overrides (avoid collisions with an existing agent’s jails):

CMS_JAIL_NAME=atlas-cms
OLLAMA_JAIL_NAME=atlas-ollama
LLAMA_CPP_JAIL_NAME=atlas-llamacpp

Notes:

• setup/git.ts already defaults to ${AGENT_NAME}-git, so GIT_JAIL_NAME is usually not required.
• If you decide to share a local LLM jail across agents, keep a single ollama jail and point both agents at the same IP instead of creating per-agent LLM jails.

Locale per agent (optional but supported)

Each agent can display in its own language without changing the host locale. Keep the host system locale stable (UTF-8), then set per-agent display/assistant locales in that agent’s .env:

DISPLAY_LOCALE=sl-SI
ASSISTANT_LOCALE=sl-SI
SYSTEM_LOCALE=sl_SI.UTF-8

For a different agent, choose different values (e.g. de-DE, ru-RU, zh-CN). Do not use legacy encodings; SYSTEM_LOCALE must remain UTF-8.

If multiple agents share one tmux server, new panes inherit the server locale. Either use separate tmux sessions per agent or set locale env vars inside each agent’s rc.d service environment.

3) Add the new gateway IP to warden0

Runtime (immediate):

sudo ifconfig warden0 inet 10.0.1.1/24 alias

Persist across reboots (choose the next free alias index):

sudo sysrc ifconfig_warden0_alias0="inet 10.0.1.1/24"

4) Update PF NAT to include both subnets

If you use an include such as /etc/pf.warden.conf, the key idea is:

warden_net = "{ 10.0.1.0/24, 192.168.72.0/24 }"
nat on $ext_if from $warden_net to any -> ($ext_if)
pass quick on warden0 inet from $warden_net to any keep state

Reload PF:

sudo pfctl -nf /etc/pf.conf
sudo pfctl -f /etc/pf.conf

5) Provision the second agent’s service jails

From the second agent repo directory:

sudo just setup-db
sudo just setup-git
sudo just setup-cms
sudo just setup -- --step ollama     # optional
sudo just setup -- --step llama-cpp  # optional

Database provisioning can be done either via just setup-db (or npm run setup -- --step db) or via Ansible playbooks in infra/ansible/playbooks/.

6) Install and start the second rc.d service

sudo just setup -- --step service
sudo service atlas onestart

bhyve note

If you deploy one agent per bhyve VM, you typically do not need any of the same-host subnet aliasing or multi-subnet PF rules. Each VM can keep a single-agent warden0 + single /24 internally.