Vind-Box: The Next-Generation Useless Machine

Vind-Box is an architectural blueprint for building Zero-Split-Brain agent systems. It uses WebAssembly (WASM) to ensure that core business logic—the "Brain"—is shared identically across every part of the stack, from Kubernetes Operators to Android apps, eliminating logic duplication and synchronization bugs.

🚀 The Ecosystem

1. The Brain (Rust/WASM): The single source of truth for logic (push_button, is_nagging).
2. The Operator (Go): Kubernetes controller that loads the WASM Brain to reconcile state.
3. The API (Spin/Rust): Cloud gateway providing web and mobile access to the machine.
4. The MCP Server (Python): Exposes the machine logic as tools for AI agents.
5. The CLI (Go): Robust terminal interface for power users.
6. The Client (Android/Kotlin): Modern mobile UI with real-time status.

🛠️ Usage

Build Everything

make build

Run the Operator

cd components/operator
go run main.go --wasm-path=../brain/target/wasm32-wasip1/release/brain.wasm

Run the API (Spin)

Local Development

# Start a local K8s proxy
kubectl proxy --port=8001 &
# Run Spin locally
cd components/api/api
spin up --variable k8s_api_url=http://localhost:8001

Kubernetes Deployment

The API is deployed to Kubernetes as a SpinApp using the Spintainer executor to handle CA certificate verification.

kubectl apply -f deploy/apps/api/

For detailed deployment instructions, see ARCHITECTURE.md.

Use the CLI

./components/cli/useless status
./components/cli/useless push

AI Integration (MCP)

Add the following to your Gemini/Claude settings:

"vind-box": {
  "command": "uv",
  "args": ["run", "--project", "./components/mcp", "python3", "server.py", "--stdio"]
}

🗺️ Roadmap (v0.1.0)

• Real-time Client Updates (WebSockets/SSE): Replace the Android app's 5-second HTTP polling with a persistent WebSocket or Server-Sent Events (SSE) connection to the Spin API. While serverless cloud platforms like Spin Cloud may restrict long-lived connections or scale-to-zero, running the API natively in Kubernetes via SpinKube gives us the flexibility to support persistent connections for real-time updates.
• Upstream Contributions: We currently use the Spintainer (SpinAppExecutor) as a concession to easily mount the Kubernetes CA certificate and ServiceAccount tokens into the Spin v4 runtime. Our goal is to contribute upstream to the Runtime Class Manager and containerd-shim-spin to seamlessly support standard Kubernetes CA certificate injection and OIDC authentication, bringing these capabilities natively to the WASM ecosystem.

📄 Documentation

• Architecture Details
• Detailed specs and architectural records are in the .specify/ directory.

⚠️ Known Limitations

For architectural constraints, including TLS/CA certificate issues when calling the Kubernetes API from Spin components, please see LIMITATIONS.md.

---

Version: 0.0.2 | License: MIT | Built with Gemini CLI