coop

README

Coop

Coop gives each software project a persistent Linux workspace for coding agents on Apple silicon. Your project stays at the same path and remains writable; agent login state and Linux-only generated files can live in project-specific volumes.

Coop uses Apple's container runtime. Docker is not required.

Install

You need macOS 26 or later on Apple silicon.

brew install sarcasticbird/tap/coop
container system start
coop doctor

The Homebrew formula installs Apple's container CLI. Start its service once after each reboot.

To build Coop from source instead, use the Go version declared in go.mod:

go install github.com/sarcasticbird/coop/cmd/coop@latest
brew install container
container system start
coop doctor

Make sure $(go env GOPATH)/bin is on your PATH.

Start an agent session

From a project checkout:

cd ~/Projects/my-app
coop init
coop codex

coop init reviews useful machine-local settings such as Linux-only dependency volumes and published development ports. It previews every change and defaults to doing nothing. You can skip it and enter an agent directly with coop codex, coop claude, or coop opencode.

On first entry, Coop offers to build the local guest image. The guest includes Git, the GitHub CLI, common shell tools, Flox, and the supported coding agents. Your repository owns application runtimes such as Go, Node.js, and Python; declare them in the project's Flox environment or in Coop's local config.

Arguments after the agent command pass through unchanged:

coop codex --help
coop claude --help
coop opencode run "fix the tests"

Everyday commands

coop [command [args...]]  Run a command in the project workspace
coop                      Open a Zsh login shell
coop init                 Review machine-local project settings
coop up                   Create or start the project workspace
coop down                 Stop it and preserve project state
coop status               Show workspace and image status
coop ls                   List all workspaces
coop tui                  Open the workspace dashboard
coop doctor               Check host requirements and configuration
coop rebuild              Rebuild after changing configured tools
coop upgrade              Update Coop's locked core toolset
coop destroy              Delete this workspace and its state volumes

Coop flags go before the guest command. For example:

coop --credentials github-work codex

coop down preserves state. coop destroy asks for confirmation and deletes the project's Coop-owned volumes.

Machine-local configuration

Coop loads:

1. ~/.config/coop/coop.toml for settings shared across projects; then
2. <project-root>/.coop.toml for this checkout.

The project file has full local authority and must stay Git-ignored. Coop refuses to load it when Git tracks it.

A common project file keeps macOS and Linux dependencies separate and exposes a development server to the host:

# .coop.toml
[tools]
packages = ["go-task", "nodejs_22"]

[[volume]]
path = "web/node_modules"

[[publish]]
guest_port = 5173
host_port = 5173

The Linux volume starts empty, so install dependencies once inside Coop. The host retains its own web/node_modules. A published guest service must listen on 0.0.0.0; it is reachable from the host on 127.0.0.1.

See the parser-tested machine-wide and project-local examples, then use the configuration reference for all supported settings.

GitHub credentials

Coop does not manage or store your source credentials. GitHub creates and revokes tokens, Git stores them through your host credential helper, and Coop reads an authorized credential only for an interactive project entry.

The credential guide provides one copy-paste path for initial GitHub setup, rotation, project authorization, and verification from both Git and gh inside Coop.

Security boundary

Coop reduces direct host exposure; it does not make untrusted code safe. Guest commands run as root, the selected project is writable, containers persist, and outbound network access is unrestricted. Guest processes can copy or retain credentials while those credentials are exposed to a session.

Read the security model before granting credentials, forwarding SSH, mounting more host directories, or seeding sensitive data.

More documentation

• Configuration: current schema, examples, and when changes take effect
• Credentials: GitHub setup and rotation plus other credential sources
• Runtime model: project selection, persistence, images, Flox, and recovery
• Security model: trust boundaries and non-promises
• Release process: contributor-only release procedure

Third-party distribution notices for the embedded image are in THIRD_PARTY_NOTICES.md.

License

Apache-2.0. See LICENSE.