Queen Configuration

Complete configuration reference for queen-rbee, the orchestrator daemon that manages job scheduling and hive coordination.

Command-Line Flags

Port Configuration

queen-rbee --port 7833

--port, -p

• Type: u16
• Default: 7833 (from QUEEN_PORT env var)
• Description: HTTP server port for the Queen API
• Example:

  queen-rbee --port 8080

Build Information

queen-rbee --build-info

--build-info

• Description: Print build information and exit
• Output: Rust channel, version, commit hash

Environment Variables

Core Configuration

Example Configuration

# Set custom port
export QUEEN_PORT=8080
 
# Set custom URL (for multi-machine setups)
export QUEEN_URL=http://queen.example.com:7833
 
# Start Queen
queen-rbee

Network Configuration

Bind Address

Queen binds to 0.0.0.0 (all interfaces) by default:

// From bin/10_queen_rbee/src/main.rs:98
let addr = SocketAddr::from(([0, 0, 0, 0], port));

This means Queen accepts connections from ANY network interface, not just localhost.

Note: The startup message says “localhost-only mode” but this is inaccurate - the actual bind is 0.0.0.0.

Port Range

Default Ports:

• Queen API: 7833
• Queen UI (dev): 7834 (proxied in production)

API Endpoints

Queen exposes the following HTTP endpoints:

Health & Info

• GET /health - Health check (no auth required)
• GET /v1/info - Service info (base URL, port, version)

Job Management

• POST /v1/jobs - Create new job
• GET /v1/jobs/{job_id}/stream - Stream job events (SSE)
• DELETE /v1/jobs/{job_id} - Cancel job

Hive Management

• POST /v1/hive/ready - Hive discovery callback
• GET /v1/heartbeats/stream - Live heartbeat stream (SSE)

System

• POST /v1/shutdown - Graceful shutdown
• GET /dev/* - Development proxy (dev mode only)

CORS Configuration

Queen includes CORS middleware for web UI access:

let cors = CorsLayer::new()
    .allow_origin(Any)
    .allow_methods(Any)
    .allow_headers(Any);

Production: Configure a reverse proxy (nginx, Caddy) with proper CORS policies instead of using Any.

Service Discovery

Hive Discovery

Queen automatically discovers hives after startup:

// Starts 5 seconds after Queen starts
tokio::spawn(async move {
    discovery::discover_hives_on_startup(&queen_url).await
});

How it works:

1. Queen starts and listens on configured port
2. After 5s delay, Queen attempts to discover hives
3. Hives register via POST /v1/hive/ready
4. Queen subscribes to hive heartbeat streams

Registries

Queen maintains several in-memory registries:

Job Registry

let job_server: Arc<JobRegistry<String>> = Arc::new(JobRegistry::new());

• Tracks active jobs
• Manages job lifecycle
• Provides SSE streams for job events

Telemetry Registry

let telemetry = Arc::new(TelemetryRegistry::new());

• Stores hive telemetry data
• Tracks worker states
• Provides real-time heartbeat streams

Development vs Production

Development Mode

# Start Queen in development
queen-rbee --port 7833
 
# UI proxied from Vite dev server (port 7834)
curl http://localhost:7833/dev/

Features:

• /dev/* routes proxy to Vite dev server
• Hot module replacement (HMR)
• Debug logging enabled

Production Mode

# Build with release profile
cargo build --release --bin queen-rbee
 
# Run production binary
./target/release/queen-rbee --port 7833

Features:

• Static files served from embedded dist/
• Optimized binary size
• No development proxy

Logging & Observability

Queen uses the narration system for observability:

use observability_narration_core::n;
 
n!("start", "Queen-rbee starting on port {}", port);
n!("listen", "Listening on http://{}", addr);
n!("ready", "Ready to accept connections");

Narration events:

• start - Queen startup
• listen - HTTP server listening
• ready - Ready to accept requests
• discovery_error - Hive discovery failures
• error - Server errors

Related Configuration

Troubleshooting

Queen Won’t Start

Check if port is in use:

lsof -i :7833

Kill process on port:

kill $(lsof -t -i:7833)

Hives Not Connecting

Verify Queen is reachable:

curl http://localhost:7833/health

Check hive configuration:

# Hive must point to correct Queen URL
rbee-hive --queen-url http://localhost:7833

Completed by: TEAM-427
Based on: bin/10_queen_rbee/src/main.rs, bin/99_shared_crates/env-config/src/lib.rs