construct-cli

README

The Construct CLI

The Construct is a single-binary CLI that boots a clean and isolated sandboxed container, preloaded with AI agents. It keeps your host free of dependency sprawl, adds optional network isolation, and works with Docker, Podman, or macOS native container runtime.

But, most importantly, it keeps your local machine safe from LLM prompt injection attacks, malware distributed this way, credentials stolen this way, and dangerous derps still being committed by AGENTS that can leave you without any of your files.

Highlights

• One command to use any AGENT inside a secured, isolated sandbox. Agents spawn from the path where you call them, without a path escape.
• Zero Config: no complex setup. The Construct just works out of the box across macOS, Linux, and Windows (WSL).
• Auto-detection: Automatically detects and uses the best available container runtime (macOS native → Podman → Docker)
• Experimental MicroVM Engine: Optional hardware-level isolation via microVMs (backend = "microvm" using microsandbox), running agents with dedicated guest Linux kernels; use it with the daemon and [daemon] mount_paths covering your project roots so the sandbox is reused, not recreated, when you switch projects
• Clean Slate: Ephemeral containers with persistent volumes for agents and packages
• Network Isolation: Optional permissive, strict, or offline network modes with allow/block lists
• SSH Agent Forwarding: Automatic detection and secure mounting of your SSH agent
• Full Clipboard Bridge: Text and image pasting support for Claude, Copilot, Antigravity, Qwen, Pi, and OMP
• Agent Browser: Headless browser automation CLI for AI agents
• Host Loopback Browsing: Headless browser agents reach host dev sites served on localhost/*.localhost via automatic TCP relays to the host
• Terminal Identity Forwarding: kitty and Ghostty terminal markers pass into the sandbox so TUIs and pi extensions render inline images correctly
• User-Defined Packages: Customize your sandbox with apt, brew, bun, npm, or pip packages
• Parallel Workflows: Git worktree management for parallel AI agent workflows

Screenshots

Available AGENTS

• Codex CLI (codex) – OpenAI's premier coding agent for GPT models
• Antigravity CLI (agy) – Google's premier code agent for Gemini models
• Claude Code (claude) – Anthropic's premier coding agent for Claude models
• GitHub Copilot CLI (copilot) – GitHub Copilot code agent with access to all Copilot supported models
• Pi Coding Agent (pi) – Earendil Works minimal extensible coding agent
• OpenCode (opencode) – OpenCode's coding agent, fast and full of open weights models
• Qwen Code (qwen) – Alibaba's coding agent for Qwen models
• Crush CLI (crush) – Charmbracelet's coding agent
• Claude Code with other providers: Zai GLM, MiniMax M2, Kimi K2, Qwen, Mimo
• Full agent list →

Quick Install

# One-line installer (macOS & Linux)
curl -fsSL https://raw.githubusercontent.com/EstebanForge/construct-cli/main/scripts/install.sh | bash

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

Detailed Installation Guide →

Quick Start

# First-time setup (builds containers, installs agents)
construct sys init

# Run an agent
construct claude "Help me refactor this function"

# Use PATH shims (after installation)
construct sys shims --install
claude "Debug my API code"  # Now available as short command

PATH shims: agents in harnesses and non-shell callers

Shell aliases only exist inside an interactive shell (the old alias system was replaced by shims). Tools that manage coding agents (orchestrators such as Paseo, IDE extensions, CI wrappers) resolve the agent binary on PATH or spawn it directly without a shell, so they never see aliases — they run the bare host binary. For users who always want agents inside the sandbox, shims also install an ns-<agent> executable that runs the real host binary directly (non-sandboxed), and installing removes the legacy managed alias block from your shell config:

construct sys shims --install        # writes real executables (default ~/.local/bin)
pi --version                          # sandboxed via Construct
ns-pi --version                       # real host binary, no sandbox
construct sys shims --list           # show state
construct sys shims --uninstall      # remove (only touches files it wrote)
construct sys shims --remove-aliases # only clean up legacy shell aliases

Shims exec construct <slug> with all arguments; stdin/stdout pass through unchanged, so agents in RPC modes (e.g. pi --mode rpc) keep streaming JSON on stdout. Host path arguments passed by orchestrators (pi --extension, --mcp-config, --session) are staged into the construct home and rewritten to their container paths automatically, so harness-driven agents run sandboxed with their bridges intact. Harnesses that accept an explicit agent binary (e.g. Paseo's PI_COMMAND) can also point straight at the shim file. Full setup guide for orchestrators (daemon mounts, PATH, troubleshooting): docs/HARNESSES.md.

Common Examples

# Strict network isolation (allowlist only)
construct claude -ct-n strict "Review my code"

# Offline run (no network)
construct agy --ct-network offline "Explain this code"

# Update all agents
construct sys update

# Install custom packages
construct sys packages --install

# Edit configuration
construct sys config

# System health check
construct sys doctor

Documentation

Getting Started

Topic	Description
Installation	Platform-specific installation, troubleshooting
Configuration	Complete config reference for all settings
Security	Container security, secret redaction, best practices

Features

Topic	Description
Hide Secrets Mode	Prevent agents from seeing raw secrets (experimental)
VM Backend	Opt-in microVM isolation via microsandbox (experimental)
Providers	Configure custom Claude API endpoints
Packages	User-defined package management
Architecture	Technical design and internals

Reference

Topic	Description
Agents	Complete list of supported agents
Clipboard	Clipboard bridge architecture
Development	Contributing and development guide
Contributing	Contribution guidelines

CLI Reference

# System commands
construct sys init              # First-time setup
construct sys doctor           # Health check
construct sys config           # Edit configuration
construct sys update           # Update agents
construct sys exec -- <cmd>    # Run command inside running container
construct sys reset            # Reset everything

# Agent commands
construct <agent>              # Run an agent (e.g., construct claude, construct agy)
construct sys shims            # Manage PATH shims (sandboxed + ns-) for agents
construct sys agents-md        # Manage AGENTS.md rules

# Development
construct sys rebuild          # Rebuild containers
construct sys config --migrate # Migrate configuration
construct --help               # Show all commands

Security

Built-in protections:

• ✅ Container isolation (agents cannot escape project directory)
• ✅ Network isolation (permissive/strict/offline modes)
• ✅ Ephemeral containers (clean slate every run)
• ✅ No path escape (agents stay in project root)
• ✅ Secret redaction (experimental) - see docs
• ✅ Optional microVM isolation (experimental, backend = "microvm") - see docs

Build integrity:

• ✅ Automated CI/CD builds via GitHub Actions
• ✅ Reproducible builds traceable to source commits
• ✅ SHA256 checksums for release verification

Complete Security Guide →

Contributing

Contributions are welcome! Please see:

• Development Guide
• Contributing Guidelines

License

MIT License - see LICENSE for details

Acknowledgments

Built with ❤️ for my kids. Go wild and experiment. Have fun.

---

Documentation: docs/ | Issues: GitHub Issues | Releases: GitHub Releases