{"id":50555385,"url":"https://github.com/angristan/netclode","last_synced_at":"2026-06-04T06:31:47.178Z","repository":{"id":331620404,"uuid":"1128434362","full_name":"angristan/netclode","owner":"angristan","description":"Self hosted cloud coding agent with k3s + kata containers + cloud hypervisor microVMs + tailscale + any harness + a nice iOS app","archived":false,"fork":false,"pushed_at":"2026-05-01T03:59:43.000Z","size":16972,"stargazers_count":129,"open_issues_count":12,"forks_count":15,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-05-01T05:20:49.660Z","etag":null,"topics":["claude-code","cloud-hypervisor","codex","coding-agent","copilot","juicefs","k3s","kata-containers","microvm","opencode","swiftui"],"latest_commit_sha":null,"homepage":"https://stanislas.blog/2026/02/netclode-self-hosted-cloud-coding-agent/","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/angristan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-05T16:22:46.000Z","updated_at":"2026-04-29T11:19:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/angristan/netclode","commit_stats":null,"previous_names":["angristan/netclode"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/angristan/netclode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angristan%2Fnetclode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angristan%2Fnetclode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angristan%2Fnetclode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angristan%2Fnetclode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/angristan","download_url":"https://codeload.github.com/angristan/netclode/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angristan%2Fnetclode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33893323,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","cloud-hypervisor","codex","coding-agent","copilot","juicefs","k3s","kata-containers","microvm","opencode","swiftui"],"created_at":"2026-06-04T06:31:46.488Z","updated_at":"2026-06-04T06:31:47.165Z","avatar_url":"https://github.com/angristan.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Netclode\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"clients/ios/Netclode/Resources/Assets.xcassets/AppIcon.appiconset/AppIcon.png\" alt=\"netclode\" width=\"120\" height=\"120\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\nSelf-hosted coding agent with microVM sandboxes and a native iOS and macOS app.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/ios-netclode.png\" alt=\"Netclode iOS App\" height=\"500\"\u003e\n  \u003cimg src=\"docs/images/macos-netclode.png\" alt=\"Netclode macOS App\" height=\"520\"\u003e\n\u003c/p\u003e\n\n## Why I built this\n\nI 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!\n\nI 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/).\n\n## What makes it nice\n\n- **Full yolo mode** - Docker, root access, install anything. The microVM handles isolation\n- **Local inference with Ollama** - Run models on your own GPU, nothing leaves your machine\n- **Tailnet integration** - Preview URLs, port forwarding, access to my infra through Tailscale\n- **JuiceFS for storage** - Storage offloaded to S3. Paused sessions cost nothing but storage\n- **Live terminal access** - Drop into the sandbox shell from the app\n- **Session history** - Auto-snapshots after each turn. Roll back workspace and chat to any previous point\n- **GitHub integration** - Clone private repos, push commits, create PRs. Per-repo scoped tokens generated on demand via a GitHub App\n- **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\n- **Multiple SDKs \u0026 providers** - Claude Code, OpenCode, Copilot, Codex SDKs with Anthropic, OpenAI, Mistral, Ollama, and more\n- **Secrets can't be stolen** - API keys never enter the sandbox. A proxy injects them on the fly for allowed hosts\n\n## How it works\n\n```mermaid\nflowchart LR\n    subgraph CLIENT[\"Client\"]\n        APP[\"iOS / macOS\u003cbr/\u003e\u003csub\u003eSwiftUI\u003c/sub\u003e\"]\n    end\n\n    subgraph VPS[\"VPS - k3s\"]\n        TS[\"Tailscale Ingress\u003cbr/\u003e\u003csub\u003eTLS - HTTP/2\u003c/sub\u003e\"]\n        CP[\"Control Plane\u003cbr/\u003e\u003csub\u003eGo\u003c/sub\u003e\"]\n        BOT[\"GitHub Bot\u003cbr/\u003e\u003csub\u003eGo\u003c/sub\u003e\"]\n        REDIS[(\"Redis\u003cbr/\u003e\u003csub\u003eSessions\u003c/sub\u003e\")]\n        POOL[\"agent-sandbox\u003cbr/\u003e\u003csub\u003eWarm Pool\u003c/sub\u003e\"]\n        JFS[(\"JuiceFS\")]\n\n        subgraph SANDBOX[\"Sandbox - Kata VM\u003cbr/\u003e\u003csub\u003eCloud Hypervisor\u003c/sub\u003e\"]\n            AGENT[\"Agent\u003cbr/\u003e\u003csub\u003eClaude / OpenCode / Copilot / Codex SDK\u003c/sub\u003e\"]\n            DOCKER[\"Docker\"]\n        end\n    end\n\n    GH[\"GitHub Webhooks\"]\n    S3[(\"S3\")]\n    LLM[\"LLM APIs\"]\n\n    APP \u003c--\u003e|\"Connect RPC\u003cbr/\u003eHTTPS/H2\"| TS\n    TS \u003c--\u003e|\"Connect RPC\u003cbr/\u003eh2c\"| CP\n    GH --\u003e|\"Webhooks\"| BOT\n    BOT \u003c--\u003e|\"Connect RPC\u003cbr/\u003eh2c\"| CP\n    CP \u003c--\u003e|\"Redis Streams\"| REDIS\n    CP \u003c--\u003e|\"Connect RPC\u003cbr/\u003egRPC/h2c\"| AGENT\n    POOL -.-\u003e|\"allocate\"| SANDBOX\n    JFS \u003c--\u003e SANDBOX\n    JFS \u003c--\u003e|\"POSIX on S3\"| S3\n    AGENT --\u003e LLM\n```\n\nThe 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.\n\nWhen 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.\n\n## Stack\n\n| Layer             | Technology                         | Purpose                                      |\n| ----------------- | ---------------------------------- | -------------------------------------------- |\n| **Host**          | Linux VPS + Ansible                | Provisioned via playbooks                    |\n| **Orchestration** | k3s                                | Lightweight Kubernetes, nice for single-node |\n| **Isolation**     | Kata Containers + Cloud Hypervisor | MicroVM per agent session                    |\n| **Storage**       | JuiceFS → S3                       | POSIX filesystem on object storage           |\n| **State**         | Redis (Streams)                    | Real-time, streaming session state           |\n| **Network**       | Tailscale Operator                 | VPN to host, ingress, sandbox previews       |\n| **API**           | Protobuf + Connect RPC             | Type-safe, gRPC-like, streams                |\n| **Control Plane** | Go                                 | Session and sandbox orchestration            |\n| **Agent**         | TypeScript/Node.js                 | SDK runner inside sandbox                    |\n| **GitHub Bot**    | Go                                 | Webhook-driven bot for @mentions and dep reviews |\n| **Secret Proxy**  | Go                                 | Injects API keys outside the sandbox         |\n| **Local LLM**     | Ollama                             | Optional, local models on GPU                |\n| **Client**        | SwiftUI (iOS 26)                   | Native iOS/macOS app                         |\n| **CLI**           | Go                                 | Debug client for development                 |\n\n## Project structure\n\n```\nnetclode/\n├── clients/\n│   ├── ios/              # iOS/Mac app (SwiftUI)\n│   └── cli/              # Debug CLI (Go)\n├── services/\n│   ├── control-plane/    # Session orchestration (Go)\n│   ├── agent/            # SDK runner (Node.js)\n│   │   └── auth-proxy/   # Adds SA token to requests (Go)\n│   ├── github-bot/       # GitHub webhook bot (Go)\n│   └── secret-proxy/     # Injects real API keys (Go)\n├── proto/                # Protobuf definitions\n├── infra/\n│   ├── ansible/          # Server provisioning\n│   └── k8s/              # Kubernetes manifests\n└── docs/\n```\n\n## Getting started\n\nSee [docs/deployment.md](docs/deployment.md) for full setup. I tried to make it as easy as possible: ideally a single playbook run.\n\nQuick version:\n\n1. Provision a VPS with nested virtualization support\n2. Run Ansible playbooks to provision the server\n3. Configure secrets (API keys, S3 credentials, Tailscale OAuth)\n4. Deploy k8s manifests\n5. Connect via Tailscale and you're good to go\n\n## Docs\n\n- [Deployment](docs/deployment.md) - Full setup\n- [Operations](docs/operations.md) - Day-to-day management\n- [Sandbox Architecture](docs/sandbox-architecture.md) - Kata VMs, JuiceFS, warm pool\n- [Session Lifecycle](docs/session-lifecycle.md) - How sessions work\n- [Session History](docs/session-history.md) - Snapshots and rollback\n- [GitHub Integration](docs/github-integration.md) - Clone repos and push commits\n- [GitHub Bot](docs/github-bot.md) - @mention bot and dependency review automation\n- [Network Access](docs/network-access.md) - Internet and Tailnet access control\n- [Secret Proxy](docs/secret-proxy.md) - API key protection architecture\n- [Web Previews](docs/web-previews.md) - Port exposure via Tailscale\n- [Terminal](docs/terminal.md) - Live shell access\n- [SDK Support](docs/sdk-support.md) - Claude, OpenCode, Copilot, Codex\n- [Agent Events](docs/agent-events.md) - Event types and streaming\n- [iOS App](clients/ios/README.md)\n- [CLI](clients/cli/README.md) - Debug CLI\n- [Control Plane](services/control-plane/README.md)\n- [Agent](services/agent/README.md)\n- [Infrastructure](infra/k8s/README.md)\n\n## Demo\n\nAll videos from the [blog post](https://stanislas.blog/2026/02/netclode-self-hosted-cloud-coding-agent/):\n\n#### Warm pool instant start\n\nNo cold start, sandboxes are pre-booted\n\n\u003cp align=\"center\"\u003e\u003cvideo src=\"https://github.com/user-attachments/assets/66bd86fb-5ffc-483a-bca2-ddbe6c9b3058\" controls muted loop\u003e\u003c/video\u003e\u003c/p\u003e\n\n#### Session pause \u0026 resume\n\nOlder sessions are automatically paused to save resources. Resume brings everything back instantly\n\n\u003cp align=\"center\"\u003e\u003cvideo src=\"https://github.com/user-attachments/assets/1900d2a0-cc6a-4d7c-a27e-10e528ded2e3\" controls muted loop\u003e\u003c/video\u003e\u003c/p\u003e\n\n#### Local inference with Ollama\n\nRun models on your own GPU\n\n\u003cp align=\"center\"\u003e\u003cvideo src=\"https://github.com/user-attachments/assets/6104b384-c337-41d1-8f06-de0e9bd98377\" controls muted loop\u003e\u003c/video\u003e\u003c/p\u003e\n\n#### CLI shell\n\nInstant sandbox access from the terminal, inspired by [sprites.dev](https://sprites.dev)\n\n\u003cp align=\"center\"\u003e\u003cvideo src=\"https://github.com/user-attachments/assets/5538604d-c74e-43f0-800a-cd3a65f57a54\" controls muted loop\u003e\u003c/video\u003e\u003c/p\u003e\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\u003cstrong\u003eGit diff view\u003c/strong\u003e\u003cbr\u003eDiff view with multi-repo support\u003cbr\u003e\u003cbr\u003e\u003cvideo src=\"https://github.com/user-attachments/assets/ab712aad-a25e-49b0-a04a-a766535949c3\" controls muted loop\u003e\u003c/video\u003e\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003cstrong\u003eLive terminal\u003c/strong\u003e\u003cbr\u003eDrop into the sandbox shell from iOS\u003cbr\u003e\u003cbr\u003e\u003cvideo src=\"https://github.com/user-attachments/assets/de2572e1-cf8d-4c5c-9ff3-56d690546848\" controls muted loop\u003e\u003c/video\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\u003cstrong\u003eSpeech input\u003c/strong\u003e\u003cbr\u003eSpeech recognition for prompts\u003cbr\u003e\u003cbr\u003e\u003cvideo src=\"https://github.com/user-attachments/assets/8d21c5fd-19e3-4680-8581-27048dd229d0\" controls muted loop\u003e\u003c/video\u003e\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003cstrong\u003eTailscale port preview\u003c/strong\u003e\u003cbr\u003eExpose sandbox ports to the tailnet\u003cbr\u003e\u003cbr\u003e\u003cvideo src=\"https://github.com/user-attachments/assets/6b7ca00f-83fe-4365-be2a-686b553b3a91\" controls muted loop\u003e\u003c/video\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fangristan%2Fnetclode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fangristan%2Fnetclode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fangristan%2Fnetclode/lists"}