knowledge-base/GHOST_SHELL_VISION.md

# Ghost Shell — Strategic Vision

**Status**: Concept phase. Do not build yet. ZLH must stabilize first.  
**Last Updated**: April 7, 2026

---

## The Core Insight

ZeroLagHub is not a game host.  
It is a **control substrate over Proxmox**.  
Gaming is the first application layer.

Strip away Minecraft and dev container presets. What remains is:

- VMID allocator
- LXC provisioning logic
- Bridge assignment model
- API-driven lifecycle management
- Agent-based execution abstraction
- PTY console streaming
- Metrics aggregation
- Versioned agent updates
- Tenant isolation enforcement
- Auth + RBAC
- Billing integration

That is not gaming infrastructure. That is an **orchestration framework**.

---

## The Layer Model

```
Layer 0 — Infrastructure
  Proxmox, Storage, Networking, Bridges, VMID ranges

Layer 1 — Control Plane (Ghost Shell Core)
  API, Auth, Provisioning logic, Agent lifecycle,
  Metrics aggregation, Isolation enforcement

Layer 2 — Execution Substrate
  LXC containers, Agent runtime

Layer 3 — Application Layer (Pluggable)
  Minecraft
  Dev environments
  Future workloads
```

Gaming lives in Layer 3.  
Everything below it is generic.  
**Ghost Shell is Layers 0–2.**

---

## What Ghost Shell Is

A branded-neutral, multi-tenant, API-first LXC control plane with agent-based execution.

More precisely: **infrastructure middleware**.

Closer to a lightweight Render, Railway, or Fly.io — but:
- Self-hosted
- On bare metal
- Your cost structure
- Proxmox-native

---

## Self-Healing as a Core Design Principle

Ghost Shell is being built by a solo operator. That constraint shapes every architectural decision in the platform and must be carried forward into Ghost Shell itself.

A platform designed for solo operation must run without continuous human supervision. This means self-healing is not a feature — it is a foundational requirement of the architecture.

**The three properties every layer must have:**

1. **Self-diagnosing** — the system knows when something is wrong without a human watching
2. **Self-recovering** — common failure modes are handled automatically
3. **Loud escalation** — the system pages a human only when it genuinely cannot recover

This is the same philosophy used in industrial control systems: design for the absence of the operator, not their presence. The operator is the exception handler, not the normal execution path.

What this means for Ghost Shell specifically:
- Agent supervision and crash recovery must be generic, not game-specific
- Lifecycle state must always be recoverable from DB alone
- Any component restart must trigger automatic re-registration and re-routing
- Quota and resource enforcement must be automatic — unbounded consumption is a 3am problem
- Notifications must surface failures without requiring dashboard monitoring

---

## Strategic Direction

**The honest answer as of April 2026: finish ZLH first, then decide.**

ZLH is what started everything. The platform will be used where it makes sense once it is stable and generating revenue. Committing to a Ghost Shell direction before ZLH has validated the platform would be premature — real users and real load will reveal which problems are worth solving at scale.

The key principle is: **the platform can be used where you choose.**  
That optionality must be preserved in every architectural decision made today.

What this means practically:
- Do not architect ZLH in ways that lock Ghost Shell to gaming
- Do not abstract prematurely in ways that stall ZLH
- Keep the constraints below so options remain open

---

## The Strategic Separation (When Ready)

**ZeroLagHub** = Product built on Ghost Shell (gaming application layer)  
**Ghost Shell** = The core platform  
**Red Castle / other ventures** = Different products built on the same governance model

One core capability, multiple potential markets:

> Governed edge execution over deterministic container environments.

---

## Critical Constraints (Must Preserve Now)

For Ghost Shell to remain viable, these rules apply to ZLH development today:

1. **Keep game logic out of core provisioning code** — Minecraft is a workload definition, not a foundation
2. **Keep the agent generic** — it runs any workload, not just game servers
3. **Keep template definitions abstract** — game types are plugins, not hardcoded paths
4. **Treat application layer as pluggable** — Layer 3 must be swappable
5. **Build self-healing at every layer** — the system must operate without continuous supervision

If Minecraft becomes embedded in lifecycle logic, Ghost Shell dies.  
If Minecraft is a plug-in workload definition, Ghost Shell lives.

These constraints should be checked in every architectural review.

---

## Phased Extraction Plan

```
Phase 1 — ZLH as application layer (NOW)
  Build ZLH on top of what will become Ghost Shell.
  Do not abstract yet.
  Close the self-healing gaps (pre-launch blockers).

Phase 2 — Stabilize core (NEXT)
  ZLH reaches: stable, operational, revenue generating.
  Runs without continuous supervision.
  Minimal rewrite pressure.

Phase 3 — Extract core into Ghost Shell
  Clean separation of Layer 1-2 from Layer 3.
  Ghost Shell becomes a named, standalone codebase.

Phase 4 — ZLH becomes one implementation of Ghost Shell
  Other products can be built on the same substrate.
  Direction chosen based on what ZLH has taught.
```

**The wrong move is abstracting too early — it will stall ZLH.**

---

## Connection to Owner Background

This architecture emerged naturally from controls engineering thinking applied to cloud infrastructure. The layer model above is structurally identical to how industrial control systems are organized (field devices → controllers → supervisory → operator interface). The self-healing requirement mirrors how industrial systems are designed: the operator is the exception handler, not the normal execution path.

That is not accidental — it is trained instinct applied to a new domain.

See `OWNER_PROFILE.md` for full context.