https://github.com/angristan/netclode
Self hosted cloud coding agent with k3s + kata containers + cloud hypervisor microVMs + tailscale + any harness + a nice iOS app
https://github.com/angristan/netclode
claude-code cloud-hypervisor codex coding-agent copilot juicefs k3s kata-containers microvm opencode swiftui
Last synced: 12 days ago
JSON representation
Self hosted cloud coding agent with k3s + kata containers + cloud hypervisor microVMs + tailscale + any harness + a nice iOS app
- Host: GitHub
- URL: https://github.com/angristan/netclode
- Owner: angristan
- Created: 2026-01-05T16:22:46.000Z (5 months ago)
- Default Branch: master
- Last Pushed: 2026-05-01T03:59:43.000Z (about 2 months ago)
- Last Synced: 2026-05-01T05:20:49.660Z (about 2 months ago)
- Topics: claude-code, cloud-hypervisor, codex, coding-agent, copilot, juicefs, k3s, kata-containers, microvm, opencode, swiftui
- Language: Swift
- Homepage: https://stanislas.blog/2026/02/netclode-self-hosted-cloud-coding-agent/
- Size: 16.2 MB
- Stars: 129
- Watchers: 1
- Forks: 15
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Netclode
Self-hosted coding agent with microVM sandboxes and a native iOS and macOS app.
## Why I built this
I wanted a self-hosted Claude Code environment I can use from my phone, with the UX I actually want. The existing cloud coding agents were a bit underwhelming when I tried them, so I built my own!
I wrote a blog post about how it works: [Building a self-hosted cloud coding agent](https://stanislas.blog/2026/02/netclode-self-hosted-cloud-coding-agent/).
## What makes it nice
- **Full yolo mode** - Docker, root access, install anything. The microVM handles isolation
- **Local inference with Ollama** - Run models on your own GPU, nothing leaves your machine
- **Tailnet integration** - Preview URLs, port forwarding, access to my infra through Tailscale
- **JuiceFS for storage** - Storage offloaded to S3. Paused sessions cost nothing but storage
- **Live terminal access** - Drop into the sandbox shell from the app
- **Session history** - Auto-snapshots after each turn. Roll back workspace and chat to any previous point
- **GitHub integration** - Clone private repos, push commits, create PRs. Per-repo scoped tokens generated on demand via a GitHub App
- **GitHub Bot** - @mention on PRs/issues to spin up a sandbox and get a response as a comment. Auto-reviews dependency update PRs from Dependabot/Renovate
- **Multiple SDKs & providers** - Claude Code, OpenCode, Copilot, Codex SDKs with Anthropic, OpenAI, Mistral, Ollama, and more
- **Secrets can't be stolen** - API keys never enter the sandbox. A proxy injects them on the fly for allowed hosts
## How it works
```mermaid
flowchart LR
subgraph CLIENT["Client"]
APP["iOS / macOS
SwiftUI"]
end
subgraph VPS["VPS - k3s"]
TS["Tailscale Ingress
TLS - HTTP/2"]
CP["Control Plane
Go"]
BOT["GitHub Bot
Go"]
REDIS[("Redis
Sessions")]
POOL["agent-sandbox
Warm Pool"]
JFS[("JuiceFS")]
subgraph SANDBOX["Sandbox - Kata VM
Cloud Hypervisor"]
AGENT["Agent
Claude / OpenCode / Copilot / Codex SDK"]
DOCKER["Docker"]
end
end
GH["GitHub Webhooks"]
S3[("S3")]
LLM["LLM APIs"]
APP <-->|"Connect RPC
HTTPS/H2"| TS
TS <-->|"Connect RPC
h2c"| CP
GH -->|"Webhooks"| BOT
BOT <-->|"Connect RPC
h2c"| CP
CP <-->|"Redis Streams"| REDIS
CP <-->|"Connect RPC
gRPC/h2c"| AGENT
POOL -.->|"allocate"| SANDBOX
JFS <--> SANDBOX
JFS <-->|"POSIX on S3"| S3
AGENT --> LLM
```
The control plane grabs a pre-booted Kata VM from the warm pool (so it's instant), forwards prompts to the agent SDK inside, and streams responses back. Redis persists events so clients can reconnect without losing anything.
When pausing, the VM is deleted but JuiceFS keeps everything in S3: workspace, installed tools, Docker images, SDK session. Resume mounts the same storage and the conversation continues as if nothing happened. Dozens of paused sessions cost practically nothing.
## Stack
| Layer | Technology | Purpose |
| ----------------- | ---------------------------------- | -------------------------------------------- |
| **Host** | Linux VPS + Ansible | Provisioned via playbooks |
| **Orchestration** | k3s | Lightweight Kubernetes, nice for single-node |
| **Isolation** | Kata Containers + Cloud Hypervisor | MicroVM per agent session |
| **Storage** | JuiceFS → S3 | POSIX filesystem on object storage |
| **State** | Redis (Streams) | Real-time, streaming session state |
| **Network** | Tailscale Operator | VPN to host, ingress, sandbox previews |
| **API** | Protobuf + Connect RPC | Type-safe, gRPC-like, streams |
| **Control Plane** | Go | Session and sandbox orchestration |
| **Agent** | TypeScript/Node.js | SDK runner inside sandbox |
| **GitHub Bot** | Go | Webhook-driven bot for @mentions and dep reviews |
| **Secret Proxy** | Go | Injects API keys outside the sandbox |
| **Local LLM** | Ollama | Optional, local models on GPU |
| **Client** | SwiftUI (iOS 26) | Native iOS/macOS app |
| **CLI** | Go | Debug client for development |
## Project structure
```
netclode/
├── clients/
│ ├── ios/ # iOS/Mac app (SwiftUI)
│ └── cli/ # Debug CLI (Go)
├── services/
│ ├── control-plane/ # Session orchestration (Go)
│ ├── agent/ # SDK runner (Node.js)
│ │ └── auth-proxy/ # Adds SA token to requests (Go)
│ ├── github-bot/ # GitHub webhook bot (Go)
│ └── secret-proxy/ # Injects real API keys (Go)
├── proto/ # Protobuf definitions
├── infra/
│ ├── ansible/ # Server provisioning
│ └── k8s/ # Kubernetes manifests
└── docs/
```
## Getting started
See [docs/deployment.md](docs/deployment.md) for full setup. I tried to make it as easy as possible: ideally a single playbook run.
Quick version:
1. Provision a VPS with nested virtualization support
2. Run Ansible playbooks to provision the server
3. Configure secrets (API keys, S3 credentials, Tailscale OAuth)
4. Deploy k8s manifests
5. Connect via Tailscale and you're good to go
## Docs
- [Deployment](docs/deployment.md) - Full setup
- [Operations](docs/operations.md) - Day-to-day management
- [Sandbox Architecture](docs/sandbox-architecture.md) - Kata VMs, JuiceFS, warm pool
- [Session Lifecycle](docs/session-lifecycle.md) - How sessions work
- [Session History](docs/session-history.md) - Snapshots and rollback
- [GitHub Integration](docs/github-integration.md) - Clone repos and push commits
- [GitHub Bot](docs/github-bot.md) - @mention bot and dependency review automation
- [Network Access](docs/network-access.md) - Internet and Tailnet access control
- [Secret Proxy](docs/secret-proxy.md) - API key protection architecture
- [Web Previews](docs/web-previews.md) - Port exposure via Tailscale
- [Terminal](docs/terminal.md) - Live shell access
- [SDK Support](docs/sdk-support.md) - Claude, OpenCode, Copilot, Codex
- [Agent Events](docs/agent-events.md) - Event types and streaming
- [iOS App](clients/ios/README.md)
- [CLI](clients/cli/README.md) - Debug CLI
- [Control Plane](services/control-plane/README.md)
- [Agent](services/agent/README.md)
- [Infrastructure](infra/k8s/README.md)
## Demo
All videos from the [blog post](https://stanislas.blog/2026/02/netclode-self-hosted-cloud-coding-agent/):
#### Warm pool instant start
No cold start, sandboxes are pre-booted
#### Session pause & resume
Older sessions are automatically paused to save resources. Resume brings everything back instantly
#### Local inference with Ollama
Run models on your own GPU
#### CLI shell
Instant sandbox access from the terminal, inspired by [sprites.dev](https://sprites.dev)
Git diff view
Diff view with multi-repo support
Live terminal
Drop into the sandbox shell from iOS
Speech input
Speech recognition for prompts
Tailscale port preview
Expose sandbox ports to the tailnet