DOCUMENTATION · MVP

Get productive
inside Duct.

A practical guide to installing the local MVP, creating an isolated workspace, working in it, and safely reviewing changes.

Early software. Duct is under active development. Today it runs local Linux workspaces through Docker (inside Lima on macOS). Remote environments and reconnectable agent sessions are future work.

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 --help

Or 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 up

On 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 dev

Run 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_ID

Detached 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-project

Apply 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-project

05 · 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]
  • image selects the Linux container image; default: alpine:3.20.
  • setup lists shell commands run on provisioning and reset.
  • ports lists container ports published on loopback.
  • env supplies environment variables; avoid committing secrets.
  • mounts maps a project-relative host path to an absolute environment path. Mode is rw or ro; writable mounts change the host path directly.
  • exclude skips project-relative paths in the initial snapshot. .git, node_modules, and .duct are 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 by duct up or duct port.
  • Controller logs: local data and logs are under Duct’s application data directory (typically ~/Library/Application Support/duct on 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.