📝 Infrastructure: How does the Hetzner multi-server fleet work and how do you ...

Date: 2026-03-23
Time: 17:05:54 UTC
Session: gspace1-261.3
Agent: backend
Confidence: 95%
Status: ✅ Documented

📋 Decision Context

Question:

How does the Hetzner multi-server fleet work and how do you add a new server?

Task: S261: Document Hetzner multi-server architecture for future agents

🎯 Decision Made

Chosen:

SANDBOX_SERVERS_JSON env var defines the fleet as a JSON array. Each entry has: id, url, apiKey, roles, priority, maxContainers. SandboxPlacementRouter parses this on startup, creates one SandboxServerClient per entry, polls health every 30s, and routes VMs using Filter→Score selection (filter by role+health+capacity, score by priority then available capacity). Sticky placement maps track sandboxId→serverId for operation routing. Adding a server: (1) yarn sandbox:bootstrap, (2) yarn sandbox:deploy:host, (3) add JSON entry to SANDBOX_SERVERS_JSON, (4) restart backend-ai-api. Zero code changes.

Options Considered:

• No alternatives documented

💭 Reasoning

The fleet is config-driven so operators never touch code when scaling. SandboxServerClient is a plain class (not NestJS) for testability and multi-instancing. The router implements the existing SandboxProvider interface so all 19+ consumer methods work transparently. Backward compat: if SANDBOX_SERVERS_JSON is not set, falls back to single-server SANDBOX_SERVER_URL → SelfHostedProvider chain.

📁 Files Involved

• APIs/backend-ai-api/src/app/infrastructure/services/sandbox/sandbox-placement-router.ts
• APIs/backend-ai-api/src/app/infrastructure/services/sandbox/sandbox-server-client.ts
• APIs/backend-ai-api/src/app/infrastructure/services/sandbox/sandbox-provider.factory.ts

🔗 Related

• Decision ID: dev_1774285554523_suu2c7t
• Session: 261
• Workspace: gspace1

Auto-generated by MCP Smart Consolidation