Shed

Shed manages persistent, VM-based development environments across multiple servers. Spin up isolated coding sessions (with Claude Code / OpenCode pre-installed), disconnect, and reconnect later to continue — backed by Firecracker microVMs on Linux or Apple Virtualization VMs on macOS Apple Silicon.

📖 Full documentation: https://charliek.github.io/shed/

Features

• Simple CLI — create and manage dev environments with minimal commands.
• Session persistence — VMs (and your tmux sessions) keep running after you disconnect.
• Multi-server — manage sheds across home servers and cloud VPS instances.
• IDE integration — native Cursor / VS Code Remote-SSH support.
• AI-ready — pre-configured for Claude Code and OpenCode workflows.
• VM backends — Firecracker microVMs (Linux) or Apple VZ (macOS Apple Silicon).
• Hardened sheds — --mounts none keeps host directories out of a shed's mounts, and on Firecracker --network isolated lets it reach the internet and nothing else, enforced by nftables on the host. Use both: on Firecracker an open shed with no mounts can still reach another running shed's 9P export on the bridge.
• Orchestrator API — mTLS service clients that create, run commands in (POST /api/sheds/{name}/exec) and delete only their own sheds, within a policy.

Quick start

Follow the packaged quickstart for your platform:

• macOS Quickstart — Homebrew + the shed-desktop approval app.
• Linux Quickstart — the shed-server deb running Firecracker.

Building from source or customizing images? See Developer Setup.

The CLI also ships a coding-agent skill — npx skills add charliek/shed (or, for Claude Code, /plugin marketplace add charliek/shed then /plugin install shed@shed).

Architecture

Three binaries:

• shed — the CLI on your developer machine.
• shed-server — the daemon on each host (HTTP API + SSH server) that runs VMs via the VZ (macOS) or Firecracker (Linux) backend.
• shed-host-agent — optional host-side credential broker (built in-tree from crates/shed-host-agent); on macOS it pairs with the shed-desktop approval app (in this monorepo under desktop/, with its shared Rust client core under crates/).

Developer Machine                Remote Server / Local Mac
┌─────────────┐   HTTP/SSH    ┌──────────────────────────────┐
│  shed CLI   │ ────────────▶ │  shed-server                 │
└─────────────┘               │   ├── HTTP API (lifecycle)   │
                              │   └── SSH server (shell/IDE) │
                              │        VZ │ Firecracker VMs  │
                              └──────────────────────────────┘

Both backends boot from layered OCI images (base / extensions / full) pulled registry-direct from ghcr.io. See Images.

Documentation

• Getting Started — quickstarts + developer setup
• CLI Reference — every command
• Configuration — client + server config
• Security Configuration — choosing a server posture and hardening sheds
• Security — the model: postures, service clients, mount selection, network profiles
• Orchestrated Sheds — driving sheds from CI or an agent runner
• Images · Storage Model
• Extensions — credential brokering
• Provisioning — .shed/ install/startup hooks + tutorials
• Desktop app — the Tauri desktop app for macOS (menu bar) and Linux (desktop/, on the shared Rust core in crates/)

Requirements

• Client: macOS or Linux (the shed CLI).
• Server (VZ): macOS 13+ on Apple Silicon (arm64); macOS 14+ for shed-desktop.
• Server (Firecracker): Linux with KVM.
• Network: Tailscale (or any private network) connecting the machines.

Security model

Shed is local-development-first: out of the box bind_address defaults to loopback (127.0.0.1), so the server is reachable only on the machine it runs on. Facing the network is opt-in, and token mode (pinned TLS + minted bearer tokens + an SSH key allowlist) is the preferred posture for anything networked — it works locally too. Open mode (plain HTTP, no tokens) stays available for a trusted private network (e.g. Tailscale), but exposing it off-loopback is explicit. Workloads run as a non-root shed user (UID 1000) with passwordless sudo. Shed targets single-user setups and is not built for multi-tenant use. In mtls mode an orchestrator can be a service client with a policy, which narrows what it can reach through the API; that is a narrow identity, not tenant isolation (Firecracker runs without its jailer, for one). Each shed can also be hardened on its own, with fewer mounts and, on Firecracker, the isolated network.

Development

See Development Setup for building from source and contributing.

License

MIT