construct

Linux only. macOS and Windows are not currently supported.

Project Notice: I am currently working on a newer, better isolated version of this tool. This repository will be archived soon in favor of the new version. Run AI coding agents (opencode) in isolated Docker containers. The agent gets its own environment — its own filesystem, its own tool installs, its own home directory — without touching your machine. Your repo is bind-mounted at its exact host path so paths, git worktrees, and relative references all work correctly.

How it works

construct run starts a long-lived daemon (constructd) in a Docker container on your host. The daemon manages session containers — one per repo. When you run construct for a folder, it either creates a new session container or attaches to the existing one.

Each session container:

• Has a persistent agent layer volume (/agent) for tool installs, home directory, and build caches — survives container restarts
• Bind-mounts your repo at its exact host path (e.g. /home/user/src/myapp)
• Bind-mounts your opencode config so your models, skills, and slash commands work identically inside the container
• Runs the agent as your host UID:GID so files written to the repo have correct ownership
• Has passwordless sudo so the agent can install system packages (apt-get install)

Not a security guarantee. A sufficiently motivated agent could escape the container. This tool is about giving the agent a clean, persistent workspace and keeping it from accidentally modifying unrelated parts of your system.

Requirements

• Docker (running on the host)
• Go 1.22+ (to build from source)
• Git (for version control)

Installation

Download a binary from the releases page and put it on your PATH:

curl -L https://github.com/mtsfoni/construct/releases/latest/download/construct-linux-amd64 \
  -o ~/.local/bin/construct && chmod +x ~/.local/bin/construct

Or build from source:

git clone https://github.com/mtsfoni/construct
cd construct
bash install.sh

install.sh builds both construct (CLI) and constructd (daemon) into ~/.local/bin.

Usage

construct [flags] [path]
construct <command> [flags] [args]

path defaults to the current working directory.

# Start a session for the current folder (base stack)
construct

# Start a session with a specific stack
construct --stack dotnet /path/to/repo

# Publish ports for dev servers
construct --stack node --port 3000 --port 5173 .

# Replay the last invocation for a folder
construct qs

# List all sessions
construct ls

# View session logs
construct logs

# Destroy a session and all its state
construct destroy

# Remove everything construct has created
construct purge

Flags

Flag	Default	Description
--stack	base	Language stack (see below)
--docker	none	Docker mode: none, dind, dood
--port	—	Publish a container port (repeatable, e.g. --port 3000)
--no-web	—	Don't auto-open the web UI
--debug	—	Drop into a shell instead of starting the agent

Supported stacks

Stack	Contents
base	Debian bookworm, Node LTS, Python 3, git, sudo, Docker CLI
node	base
dotnet	base + .NET 10 SDK
go	base + Go toolchain
python	base + pip, venv
ruby	base + Ruby, Bundler, Jekyll
base-ui	base + Playwright MCP + Chromium
dotnet-ui	dotnet + Playwright MCP + Chromium

Credentials

Credentials are stored as .env files and sourced into the container at startup. They are never passed as Docker env vars.

# Set a global credential (available in all sessions)
construct config cred set ANTHROPIC_API_KEY=sk-ant-...

# Set a per-folder credential (only for sessions in this folder)
construct config cred set OPENAI_API_KEY=sk-... --folder /path/to/repo

# List credentials
construct config cred list

# Remove a credential
construct config cred unset ANTHROPIC_API_KEY

Global credentials live in ~/.config/construct/credentials/global/. Per-folder credentials live in ~/.config/construct/credentials/folders/<slug>/.

Docker modes

Mode	Description
none (default)	No Docker access inside the container
dind	Private Docker-in-Docker daemon — the agent gets its own isolated Docker environment
dood	Docker-outside-of-Docker — the agent shares your host Docker socket. Gives full host Docker access; use with caution

Project structure

cmd/construct/          CLI entry point
cmd/constructd/         Daemon entry point
embedfs/stacks/         Embedded Dockerfiles for each stack
internal/
  auth/                 Credential storage (.env files)
  bootstrap/            Daemon startup and lifecycle
  cli/                  CLI command implementations
  client/               Unix socket client (daemon IPC)
  config/               Config dir resolution
  daemon/
    session/            Session lifecycle (create, start, stop, destroy)
    server/             Unix socket server (newline-delimited JSON)
    registry/           Session state persistence
  stacks/               Stack image names and build context
SPEC/                   Design specs
REQS/                   Requirements