Configuration

Citadel is configured through a YAML manifest file that defines the node's identity and services, plus environment variables for runtime behavior.

Manifest File

The citadel.yaml manifest is generated by citadel init. It is the source of truth for your node's configuration.

Example

node:
  name: gpu-server-01
  tags:
    - gpu
    - production
  org_id: org_abc123

services:
  - name: vllm
    compose_file: services/vllm.yml
  - name: ollama
    compose_file: services/ollama.yml

Fields

Field	Type	Description
node.name	string	Display name for this node
node.tags	list	Tags for classification and filtering
node.org_id	string	Organization identifier (set during device authorization)
services	list	Services to run on this node
services[].name	string	Service name (vllm, ollama, llamacpp, extraction)
services[].type	string	"docker" or "native" (default: auto-detect)
services[].compose_file	string	Path to Docker Compose file (for docker services)
services[].port	int	Port number (for native services)

Manifest Discovery

Citadel locates the manifest using the global config file, which points to the node configuration directory:

1. Read the global config at the platform-specific config path (see below)
2. The node_config_dir field in the global config points to the directory containing citadel.yaml
3. If node_config_dir is not set, fall back to ~/citadel-node/citadel.yaml

If no manifest is found, Citadel prompts you to run citadel init.

Platform-Specific Paths

Config Directory

The global config file (config.yaml) lives in the platform-specific config directory:

Platform	Config Directory
Linux	/etc/citadel/
macOS	/usr/local/etc/citadel/
Windows	C:\ProgramData\Citadel\

Node Directory

The default node configuration directory (containing citadel.yaml and service files):

Platform	Node Directory
Linux / macOS	~/citadel-node/
Windows	%USERPROFILE%\citadel-node\

Network State

AceTeam Network connection state is stored in:

~/.citadel-node/network/

This directory persists across restarts so the node reconnects automatically without re-authentication.

Environment Variables

Variable	Default	Description
REDIS_URL	redis://redis.aceteam.ai:6379	Redis connection URL for the job queue
REDIS_PASSWORD	(none)	Redis authentication password
WORKER_QUEUE	jobs:v1:gpu-general	Redis Stream queue name to consume from
CITADEL_AUTH_HOST	https://aceteam.ai	Auth service URL for device authorization
CITADEL_DEVICE_CODE	(none)	Device code from the authorization flow, used for config lookup
CITADEL_VLLM_HOST	127.0.0.1	Node-local IP address where Citadel should dial an externally managed vLLM server
CITADEL_VLLM_HOST_PORT	8201	Host port where Citadel should dial vLLM

Environment variables override default values. Where a corresponding command-line flag exists, the flag takes precedence.

Warning: CITADEL_VLLM_HOST is a dial target, not an access-control setting. If an externally managed vLLM server binds to a public interface, that unauthenticated API is publicly exposed unless you restrict it with a firewall or another authenticated proxy. Prefer a loopback-only bind whenever the server and Citadel run on the same node.