{"id":45446468,"url":"https://github.com/mtsfoni/construct","last_synced_at":"2026-04-02T00:02:02.301Z","repository":{"id":339877713,"uuid":"1163633619","full_name":"mtsfoni/construct","owner":"mtsfoni","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-22T21:34:35.000Z","size":12555,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-23T11:57:52.607Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mtsfoni.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-21T23:04:29.000Z","updated_at":"2026-03-22T21:34:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mtsfoni/construct","commit_stats":null,"previous_names":["mtsfoni/construct"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/mtsfoni/construct","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtsfoni%2Fconstruct","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtsfoni%2Fconstruct/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtsfoni%2Fconstruct/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtsfoni%2Fconstruct/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mtsfoni","download_url":"https://codeload.github.com/mtsfoni/construct/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtsfoni%2Fconstruct/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31293139,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-22T04:02:40.175Z","updated_at":"2026-04-02T00:02:02.270Z","avatar_url":"https://github.com/mtsfoni.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# construct\n\n\u003e **Linux only.** macOS and Windows are not currently supported.\n\nRun 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.\n\n## How it works\n\n`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.\n\nEach session container:\n- Has a persistent **agent layer volume** (`/agent`) for tool installs, home directory, and build caches — survives container restarts\n- Bind-mounts your **repo at its exact host path** (e.g. `/home/user/src/myapp`)\n- Bind-mounts your **opencode config** so your models, skills, and slash commands work identically inside the container\n- Runs the agent as **your host UID:GID** so files written to the repo have correct ownership\n- Has **passwordless sudo** so the agent can install system packages (`apt-get install`)\n\n\u003e **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.\n\n## Requirements\n\n- Docker (running on the host)\n- Go 1.22+ (to build from source)\n\n## Installation\n\nDownload a binary from the [releases page](https://github.com/mtsfoni/construct/releases) and put it on your `PATH`:\n\n```bash\ncurl -L https://github.com/mtsfoni/construct/releases/latest/download/construct-linux-amd64 \\\n  -o ~/.local/bin/construct \u0026\u0026 chmod +x ~/.local/bin/construct\n```\n\nOr build from source:\n\n```bash\ngit clone https://github.com/mtsfoni/construct\ncd construct\nbash install.sh\n```\n\n`install.sh` builds both `construct` (CLI) and `constructd` (daemon) into `~/.local/bin`.\n\n## Usage\n\n```\nconstruct [flags] [path]\nconstruct \u003ccommand\u003e [flags] [args]\n```\n\n`path` defaults to the current working directory.\n\n```bash\n# Start a session for the current folder (base stack)\nconstruct\n\n# Start a session with a specific stack\nconstruct --stack dotnet /path/to/repo\n\n# Publish ports for dev servers\nconstruct --stack node --port 3000 --port 5173 .\n\n# Replay the last invocation for a folder\nconstruct qs\n\n# List all sessions\nconstruct ls\n\n# View session logs\nconstruct logs\n\n# Destroy a session and all its state\nconstruct destroy\n\n# Remove everything construct has created\nconstruct purge\n```\n\n### Flags\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--stack` | `base` | Language stack (see below) |\n| `--docker` | `none` | Docker mode: `none`, `dind`, `dood` |\n| `--port` | — | Publish a container port (repeatable, e.g. `--port 3000`) |\n| `--no-web` | — | Don't auto-open the web UI |\n| `--debug` | — | Drop into a shell instead of starting the agent |\n\n## Supported stacks\n\n| Stack | Contents |\n|-------|----------|\n| `base` | Debian bookworm, Node LTS, Python 3, git, sudo, Docker CLI |\n| `node` | base |\n| `dotnet` | base + .NET 10 SDK |\n| `go` | base + Go toolchain |\n| `python` | base + pip, venv |\n| `ruby` | base + Ruby, Bundler, Jekyll |\n| `base-ui` | base + Playwright MCP + Chromium |\n| `dotnet-ui` | dotnet + Playwright MCP + Chromium |\n\n## Credentials\n\nCredentials are stored as `.env` files and sourced into the container at startup. They are never passed as Docker env vars.\n\n```bash\n# Set a global credential (available in all sessions)\nconstruct config cred set ANTHROPIC_API_KEY=sk-ant-...\n\n# Set a per-folder credential (only for sessions in this folder)\nconstruct config cred set OPENAI_API_KEY=sk-... --folder /path/to/repo\n\n# List credentials\nconstruct config cred list\n\n# Remove a credential\nconstruct config cred unset ANTHROPIC_API_KEY\n```\n\nGlobal credentials live in `~/.config/construct/credentials/global/`. Per-folder credentials live in `~/.config/construct/credentials/folders/\u003cslug\u003e/`.\n\n## Docker modes\n\n| Mode | Description |\n|------|-------------|\n| `none` (default) | No Docker access inside the container |\n| `dind` | Private Docker-in-Docker daemon — the agent gets its own isolated Docker environment |\n| `dood` | Docker-outside-of-Docker — the agent shares your host Docker socket. Gives full host Docker access; use with caution |\n\n## Project structure\n\n```\ncmd/construct/          CLI entry point\ncmd/constructd/         Daemon entry point\nembedfs/stacks/         Embedded Dockerfiles for each stack\ninternal/\n  auth/                 Credential storage (.env files)\n  bootstrap/            Daemon startup and lifecycle\n  cli/                  CLI command implementations\n  client/               Unix socket client (daemon IPC)\n  config/               Config dir resolution\n  daemon/\n    session/            Session lifecycle (create, start, stop, destroy)\n    server/             Unix socket server (newline-delimited JSON)\n    registry/           Session state persistence\n  stacks/               Stack image names and build context\nSPEC/                   Design specs\nREQS/                   Requirements\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmtsfoni%2Fconstruct","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmtsfoni%2Fconstruct","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmtsfoni%2Fconstruct/lists"}