Skip to content

Quick Start

Get up and running with Shed in a few minutes.

Prerequisites

  • macOS Apple Silicon — Homebrew (recommended) or Go 1.24+ for source builds
  • Linux with KVM — deb package (recommended) or Go 1.24+ for source builds
  • Docker (for VM image management)
  • Tailscale (or other private network) if connecting to remote servers

Install

brew install charliek/tap/shed

This installs both shed (CLI) and shed-server, generates a default server config with the VZ backend, codesigns the server binary, and sets up a launchd service.

For credential brokering (SSH agent forwarding, AWS credentials, Docker registry auth), also install the host agent:

brew install charliek/tap/shed-host-agent

Edit the server config at $(brew --prefix)/etc/shed/server.yaml to configure credentials and extensions, then start the services:

brew services start shed
brew services start shed-host-agent  # if installed

See VZ Setup for the full macOS setup guide.

Download and install the .deb from the latest release:

VERSION=0.3.3  # replace with desired version
wget https://github.com/charliek/shed/releases/download/v${VERSION}/shed-server_${VERSION}_amd64.deb
sudo dpkg -i shed-server_${VERSION}_amd64.deb

This installs shed (CLI) and shed-server, generates a default Firecracker server config, and sets up a systemd service.

Complete the Firecracker infrastructure setup:

sudo shed-server setup
sudo shed-server pull-images
sudo systemctl start shed-server

See Firecracker Setup for the full Linux setup guide.

Build from Source

git clone https://github.com/charliek/shed.git
cd shed
make build

# Or install the CLI only
go install github.com/charliek/shed/cmd/shed@latest

See VZ Setup or Firecracker Setup for server setup instructions when building from source.

Add a Server

Register a server that has shed-server running:

shed server add my-server.tailnet.ts.net --name my-server

This connects to the server, retrieves its SSH host key, and saves the configuration.

Create a Shed

# Create an empty shed
shed create my-project

# Or clone a repository
shed create my-project --repo git@github.com:user/repo.git

# Or mount a local directory as the workspace
shed create my-project --local-dir ~/projects/my-project

Once you have a few sheds, shed system df shows what's on disk and shed system prune reclaims unused space. See Disk Management.

Connect

Direct Shell

shed console my-project

Opens a bash shell in the VM. Exits when you disconnect.

Persistent Session

shed attach my-project

Opens a tmux session that persists after you disconnect. Detach with Ctrl-B D and reconnect later with the same command.

IDE Integration

Generate SSH config entries for VS Code or Cursor:

# Preview the config
shed ssh-config my-project

# Install to ~/.ssh/config
shed ssh-config --all --install

Then connect using VS Code Remote-SSH to shed-my-project.

Common Workflows

Run a coding agent

# Create a shed and attach to a persistent session
shed create myproj --repo user/repo
shed attach myproj

# Inside the session, start Claude Code
claude

# Detach with Ctrl-B D - the agent keeps running
# Later, reattach to see progress
shed attach myproj

Multiple sessions

# Attach to a named session
shed attach myproj --session debug

# List all sessions
shed sessions --all

Port forwarding

# Start tunnels for web development
shed tunnels start myproj -t 3000:3000

# Run in background
shed tunnels start myproj -t 3000:3000 -d

Next Steps