01 · INSTALL
Get Duct
Duct is an early MVP and does not yet publish prebuilt binaries. Download the source archive or clone the repository and build the CLI with Go.
Requirements
- macOS: Apple Silicon or Intel Mac, Homebrew, Lima, and Docker CLI. Install runtime tools with
brew install lima docker. Duct uses Lima with Apple Virtualization and Docker Engine in its Linux VM; Docker Desktop is not required. - Linux: a running Docker Engine and Go for building from source.
- Go: Go 1.21 or newer to build current source.
Build from source
unzip duct-main.zip
cd duct-main
go build -o duct ./cmd/duct
./duct --helpOr clone with git clone [email protected]:aakashsell/duct.git. Keep the resulting executable on your PATH to invoke it from any project.
02 · FIRST RUN
Start a project
From a project directory, run duct up. It creates an environment from the current project if needed, starts it, and starts Duct’s local controller automatically.
cd path/to/my-project
duct upOn first use, macOS may initialize the Lima Linux VM and download container images, so startup takes longer. Later starts reuse the VM and environment. Declared ports are printed as local URLs by duct up.
Use duct list to see environments. Project files are snapshotted into /workspace; they are not bind-mounted from the host by default.
03 · WORK
Use the environment
Open an interactive shell with duct shell my-project. It starts in /workspace, where the imported project files live.
duct shell my-project
# inside the environment
pwd
npm install
npm run devRun one-off commands or start detached processes:
duct run my-project -- go test ./...
duct run my-project --detach -- npm run dev
duct sessions my-project
duct attach SESSION_IDDetached command sessions keep running if the CLI disconnects, and their output can be inspected later. The current interactive shell is tied to the client connection; persistent reconnectable shells and agent input are not implemented yet.
04 · CHANGE REVIEW
Keep or discard work
Workspace edits stay isolated until explicitly applied. Review changes, then apply them to the host project:
duct diff my-project
duct apply my-projectApply checks that host files have not changed since environment creation. If it finds a conflict, it refuses to apply rather than overwrite newer host edits. Reset restores the original baseline; destroy permanently removes the environment data.
duct reset my-project
duct destroy my-project05 · PROJECT CONFIG
Describe the environment
An optional duct.yaml in the project root describes the image, setup commands, ports, variables, mounts, and snapshot exclusions.
image: node:22-alpine
ports: [3000]
env: { NODE_ENV: development }
setup: [npm install]
mounts: ["./dist:/workspace/dist"]
exclude: [.next, dist]imageselects the Linux container image; default:alpine:3.20.setuplists shell commands run on provisioning and reset.portslists container ports published on loopback.envsupplies environment variables; avoid committing secrets.mountsmaps a project-relative host path to an absolute environment path. Mode isrworro; writable mounts change the host path directly.excludeskips project-relative paths in the initial snapshot..git,node_modules, and.ductare excluded by default.
Mounts intentionally make selected host paths visible inside the environment.
06 · CLI
Command reference
duct up [PROJECT_DIR]Create if needed and start the project environment.
duct create [--name NAME] [PROJECT_DIR]Create without starting.
duct listList environments and their state.
duct start ENV / duct stop ENVStart or stop an environment.
duct shell ENVOpen an interactive shell at /workspace.
duct run ENV -- COMMANDRun a command; add --detach for a background session.
duct sessions ENV / duct attach SESSIONInspect sessions or stream session output.
duct interrupt SESSIONInterrupt a running command session.
duct port ENV CONTAINER_PORTPrint the local address for a published port.
duct diff ENV / duct apply ENVReview workspace changes or apply them to the host.
duct reset ENV / duct destroy ENVRestore the baseline or remove an environment.
07 · RUNTIME & SAFETY
Where it runs—and what isolation means
On macOS, Duct manages one shared Lima Linux VM backed by Apple Virtualization and runs each development environment as a Docker container inside it. On Linux, it uses the local Docker Engine. The same CLI workflow is intended to hide runtime differences.
Containers are not a hardened security boundary for hostile code. Duct does not yet enforce robust outbound or private-network egress policy. It avoids privileged containers and Docker socket mounts, publishes only declared ports to loopback, and copies project files into runtime-managed storage by default. Declared host mounts intentionally expose their selected paths.
08 · TROUBLESHOOTING
If something gets stuck
- First startup takes a while: Lima may initialize the VM or Docker may download the image. Duct prints progress in the terminal.
- Docker unavailable on Linux: ensure Docker Engine is installed, running, and accessible to your user.
- Port not reachable: declare the container port under
ports, restart, then use the URL printed byduct uporduct port. - Controller logs: local data and logs are under Duct’s application data directory (typically
~/Library/Application Support/ducton macOS or the user config directory on Linux). - Still stuck: report the OS, command, and relevant log excerpt in GitHub Issues. Remove secrets before sharing logs.
09 · ROADMAP
What Duct is growing toward
The current focus is making the local workflow seamless and dependable. The longer-term architecture is designed to add remote runtimes, reconnectable interactive and agent sessions, editor access, checkpoints, cheap environment forks, and eventually managed compute—without requiring these for the local MVP.
Follow development and contribute on GitHub.