Skip to content

INSTALLATION.md

Latest commit

 

History

History
426 lines (297 loc) · 10 KB

INSTALLATION.md

File metadata and controls

426 lines (297 loc) · 10 KB
Raw

Installation Guide

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

Table of Contents

Quick Install

Fastest Method (Recommended)

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. Print the construct sys init follow-up command

Alternative: Homebrew

brew install EstebanForge/tap/construct-cli

Platform-Specific Installation

macOS

Requirements

  • macOS 26+ for the native container runtime (the gate construct enforces)
  • macOS 13+ supported with Docker Desktop or OrbStack
  • Homebrew (optional, for easier updates)

Container Runtime Options

Option 1: Native Container Runtime (macOS 26+)

  • 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://install.microsandbox.dev | 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://install.microsandbox.dev | 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/cmd/construct@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 (env var, no flags)
curl -fsSL https://raw.githubusercontent.com/EstebanForge/construct-cli/main/scripts/install.sh | VERSION=1.17.9 bash

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

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

mise

macOS & Linux

# Install globally (or drop -g to pin per-project)
mise use -g github:EstebanForge/construct-cli

# Update to the latest release
mise upgrade github:EstebanForge/construct-cli

# Uninstall
mise uninstall github:EstebanForge/construct-cli

mise resolves the GitHub release assets directly (per-platform tarballs, no tap or plugin needed). New releases appear once they age past mise's minimum_release_age supply-chain guard.

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. Pull or build the sandbox image (first run only; the microVM backend pulls construct-box from GHCR)
  4. Agents ship baked in the image at /usr/local/bin; user-tier packages from packages.toml install into the home directory
  5. Create ct alias if possible

Container Runtime Setup

Verify Runtime Detection

construct sys doctor

Expected output:

✓ Runtime backend: docker (or podman / container / microvm)
✓ Configuration: ~/.config/construct-cli
✓ Image: construct-box present (microvm) / built (docker)
✓ Agents: installed

Exact check names and statuses vary by backend; construct sys doctor --json gives the machine-readable report.

Manual Runtime Configuration

If auto-detection fails, specify runtime explicitly:

# ~/.config/construct-cli/config.toml
[runtime]
backend = "podman"  # or "auto", "container", "docker", "microvm"

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 the native runtime (macOS 26+)
# 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: native runtime requires macOS 26

The built-in container runtime gate needs macOS 26 or later; on older macOS, 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

# Legacy engine volumes (only exist on installs from before the baked image;
# current state lives in ~/.config/construct-cli/home and does not need manual cleanup)
docker volume rm construct-agents 2>/dev/null
docker volume rm construct-packages 2>/dev/null
podman volume rm construct-agents 2>/dev/null
podman volume rm construct-packages 2>/dev/null

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