Installation Guide

August 22, 2026 · View on GitHub

Detailed installation instructions for The Construct CLI across different platforms and environments.

Table of Contents

Quick Install

curl -fsSL https://raw.githubusercontent.com/EstebanForge/construct-cli/main/scripts/install.sh | bash

This will:

  1. Download the latest binary for your platform
  2. Install to /usr/local/bin
  3. Run first-time setup automatically

Alternative: Homebrew

brew install EstebanForge/tap/construct-cli

Platform-Specific Installation

macOS

Requirements

  • macOS 14+ (Sonoma) or later for native container runtime
  • macOS 13+ supported with Docker Desktop or OrbStack
  • Homebrew (optional, for easier updates)

Container Runtime Options

Option 1: Native Container Runtime (macOS 14+)

  • Built into macOS
  • No additional software required
  • Best performance
  • Auto-detected by Construct

Option 2: Docker Desktop

  • Download from docker.com
  • Start Docker Desktop before running Construct
  • Works on macOS 13+

Option 3: OrbStack

  • Download from orbstack.dev
  • Lightweight alternative to Docker Desktop
  • Auto-detected if available

Option 4: MicroVM Isolation (Experimental)

  • Install microsandbox: curl -fsSL https://msb.sh | sh
  • Set backend = "microvm" in ~/.config/construct-cli/config.toml under [runtime]
  • Runs sandboxes with dedicated Linux guest kernels via Apple Hypervisor.framework

Installation Steps

# Using install script (recommended)
curl -fsSL https://raw.githubusercontent.com/EstebanForge/construct-cli/main/scripts/install.sh | bash

# Or using Homebrew
brew install EstebanForge/tap/construct-cli

# Verify installation
construct version

Linux

Requirements

  • Linux kernel 5.15+ recommended
  • Podman (recommended) or Docker
  • Systemd for service management (optional)

Container Runtime Setup

Option 1: Podman (Recommended)

# Install Podman (Ubuntu/Debian)
sudo apt update
sudo apt install -y podman

# Enable user namespaces
echo "user.max_user_namespaces=15000" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# Configure subuid/subgid for your user
sudo usermod --add-subuids --range 100000-165535 $USER
sudo usermod --add-subgids --range 100000-165535 $USER

Option 2: Docker

# Install Docker (Ubuntu/Debian)
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

# Log out and back in for group changes to take effect

Option 3: MicroVM Isolation (Experimental)

# Install microsandbox
curl -fsSL https://msb.sh | sh

# Ensure KVM access (/dev/kvm)
sudo usermod -aG kvm $USER

# Set backend in config.toml: [runtime] backend = "microvm"

Installation Steps

# Download and install
curl -fsSL https://raw.githubusercontent.com/EstebanForge/construct-cli/main/scripts/install.sh | bash

# Or build from source (if you prefer)
go install github.com/EstebanForge/construct-cli@latest

Windows (WSL)

Requirements

  • Windows 11 or Windows 10 with WSL2 enabled
  • Ubuntu WSL or other Debian-based distro
  • Follow Linux installation instructions within WSL

WSL2 Setup

# In PowerShell (Admin)
wsl --install
wsl --set-default-version 2

Then follow the Linux installation instructions inside WSL.

Installation Methods

Homebrew

macOS & Linux

# Add tap and install
brew install EstebanForge/tap/construct-cli

# Update to latest version
brew upgrade construct-cli

# Uninstall
brew uninstall construct-cli

One-Line Script

Universal (Bash/Zsh)

curl -fsSL https://raw.githubusercontent.com/EstebanForge/construct-cli/main/scripts/install.sh | bash

Script options:

# Install specific version
curl -fsSL https://raw.githubusercontent.com/EstebanForge/construct-cli/main/scripts/install.sh | bash -s -- --version 1.6.0

# Install to custom directory
curl -fsSL https://raw.githubusercontent.com/EstebanForge/construct-cli/main/scripts/install.sh | bash -s -- --prefix ~/local/bin

# Install beta version
curl -fsSL https://raw.githubusercontent.com/EstebanForge/construct-cli/main/scripts/install.sh | CHANNEL=beta bash

Manual Binary Download

Direct download

# Download latest release for your platform
wget https://github.com/EstebanForge/construct-cli/releases/latest/download/construct-linux-amd64
chmod +x construct-linux-amd64
sudo mv construct-linux-amd64 /usr/local/bin/construct

Available platforms:

  • construct-linux-amd64
  • construct-linux-arm64
  • construct-darwin-amd64 (macOS Intel)
  • construct-darwin-arm64 (macOS Apple Silicon)

Post-Installation

First Run Setup

After installation, run the first-time setup:

construct sys init

This will:

  1. Create configuration directory: ~/.config/construct-cli/
  2. Generate default config.toml
  3. Build container images (first run only, ~5-10 minutes)
  4. Install agents to persistent volume
  5. Create ct alias if possible

Container Runtime Setup

Verify Runtime Detection

construct sys doctor

Expected output:

✓ Container runtime detected: podman
✓ Runtime version: 4.9.4
✓ Config directory: ~/.config/construct-cli
✓ Container images: built
✓ Agents installed: 18

Manual Runtime Configuration

If auto-detection fails, specify runtime explicitly:

# ~/.config/construct-cli/config.toml
[runtime]
engine = "podman"  # or "docker" or "container"

Verification

Test your installation:

# Check version
construct version

# Run a simple agent command
construct claude "Say hello"

# Check system health
construct sys doctor

Troubleshooting

Common Issues

"No container runtime found"

Solution: Install a container runtime

# macOS: Install Docker Desktop or use native runtime (macOS 14+)
# Linux: Install Podman or Docker

"Permission denied" when running construct

Solution: Check binary permissions

chmod +x /usr/local/bin/construct

"construct: command not found"

Solution: Verify installation path

# Check if construct is in PATH
which construct

# If not found, add to PATH or use full path
export PATH=$PATH:/usr/local/bin

Platform-Specific Problems

macOS: "container runtime not available on macOS 13"

Solution: Install Docker Desktop or OrbStack

# Install OrbStack (lightweight)
brew install --cask orbstack

Linux: "user namespaces not enabled"

Solution: Enable user namespaces

echo "user.max_user_namespaces=15000" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Linux: "Cannot connect to Podman socket"

Solution: Start Podman service

# Systemd systems
sudo systemctl start podman
sudo systemctl enable podman

# Or use rootless podman
podman system service start

WSL: "Container commands not working"

Solution: Ensure WSL2 is enabled

# In PowerShell (Admin)
wsl --set-default-version 2

Uninstallation

Remove Construct Binary

# If installed via script
sudo rm /usr/local/bin/construct

# If installed via Homebrew
brew uninstall construct-cli

# If installed via go install
rm ~/go/bin/construct

Remove Configuration and Data

# Remove config directory
rm -rf ~/.config/construct-cli

# Remove persistent volumes (Docker)
docker volume rm construct-cli-agent-data
docker volume rm construct-cli-agent-work

# Remove persistent volumes (Podman)
podman volume rm construct-cli-agent-data
podman volume rm construct-cli-agent-work

Remove Host Aliases

# Remove aliases installed by Construct
construct sys aliases --uninstall

# Or manually remove from shell config
# Edit ~/.bashrc, ~/.zshrc, etc. and remove construct/ct aliases

Next Steps

After installation:

  1. Read the Configuration Guide to customize Construct
  2. Check out Security Guide for hardening your setup
  3. Explore Providers Guide to use custom Claude endpoints
  4. See Examples for common workflows

Getting Help