mkenv Documentation

Overview

mkenv is a CLI that builds and runs per-project developer containers using Docker with security-focused defaults, disposable sessions, and caching for language tooling. It exists for devs who would rather yeet a container than reimage their laptop.

This documentation assumes you already live inside a terminal, know Docker basics, and understand that trusting random repos is a losing bet. We cover how to install, run, and bend mkenv without touching YAML.

Installation

Platform: macOS only right now. Linux is on the radar, Windows likely via WSL later. Bring Docker Desktop or equivalent.

Prerequisites

macOS 12+ on Apple Silicon.
Docker Desktop 4.x or Docker Engine with virtualization enabled.
Terminal basics (zsh/bash) and permissions to install binaries to $PATH.

Download & Install

Grab the latest darwin-arm64 binary from GitHub Releases:

curl -L https://github.com/0xa1bed0/mkenv/releases/download/latest/mkenv-darwin-arm64 -o mkenv
chmod +x mkenv
sudo mv mkenv /usr/local/bin/

Confirm it's on your PATH:

mkenv --version

Ensure Docker is running before you launch containers.

Quickstart

Clone or enter the repo you want to sandbox.
Run mkenv ..
mkenv inspects manifests, builds a secure Docker image, and launches it.
You land inside a non-root shell with tools installed; open your editor inside if you want it confined.

First run builds the full image and primes caches for package managers, compilers, language servers, and editor plugins. Subsequent runs reuse cached layers, so containers spin up quickly unless you force a rebuild.

Commands

All commands accept -h/--help for usage details.

`mkenv` / `mkenv run`

Build (if necessary) and run a dev container for the current project.

mkenv run [PATH] [flags]

Path defaults to ..
Analyzes the project, builds image, starts shell with mounts and caches.

Flags

Flag	Type	Description	Default
`--tools`	comma list	Extra tools to preinstall (e.g. `nvim,tmux,ripgrep`).	none
`--langs`	comma list	Hint runtimes to prioritize (node,go,python,rust).	auto-detect
`--volume`	comma list	Mount additional host directories inside the container. Support realtive path (e.g. "~/foo:~/foo")	project dir only
`--rebuild`	bool	Ignore cache and rebuild the image from scratch.	false
`--shell`	string	Preferred shell to launch inside the container (`bash`, `zsh`, `fish`).	zsh
`--entrypoint`	string	Preferred entrypoint (e.g. "tmux")	none

`mkenv attach`

Attach another shell or process to an existing container for the same project.

mkenv attach [PATH]

Matches containers based on project fingerprint.
Useful for running GUI editors or additional terminals inside the same sandbox.

`mkenv list`

List managed containers, images, and cache entries tracked by mkenv.

mkenv list [--verbose]

Shows project path, container ID, status.
--verbose adds cache location details.

`mkenv clean`

Remove containers, images, and caches created by mkenv for a project or for all projects.

mkenv clean [PATH] [--all]

Without flags, cleans the current project.
--all wipes everything including shared caches.

`mkenv completion`

Emit shell completion scripts for bash, zsh, or fish.

mkenv completion [bash|zsh|fish]

Pipe the output into your shell config.

`mkenv help`

Display inline help for commands/subcommands.

mkenv help [command]

Configuration & Behavior

Stack Detection

mkenv scans the project directory for manifests like package.json, pnpm-lock.yaml, poetry.lock, requirements.txt, go.mod, Cargo.toml, Gemfile, and Dockerfile fragments. Signals drive which language runtimes, package managers, and helper tools get baked into the image.

This scan also figures out sensible build contexts, env vars, and whether to preload IDE tooling like language servers.

Security Defaults

Containers run as a non-root user with a locked-down $HOME.
Only the project directory mounts in read-write; no broad /Users/you mounts.
Shell history files are sanitized/disabled so secrets never spill back out.
SSH agent sockets and host credentials are excluded unless explicitly mounted.

Caching

Language caches live under ~/Library/Caches/mkenv (configurable later). Node modules, Go build cache, Rust crates, pip wheels, and editor plugin directories all reuse prior layers. Rebuild triggers only when relevant manifest or lockfiles change.

The contract is simple: run mkenv ., get a clean environment with the right tooling, no mental overhead, and a fast exit path if something looks off.

Guardrails

mkenv also scans your project files once to see if you about to mount anything sensitive to the container. If it will find any suspitious files (like your ssh keys, tokens, etc...) it will warn you and let you review them before starting environment.

The sandbox could potentially have credential stealers sneaked through supply chain attack - because of this we highly recoomend to no mount any secrets to the sandbox and keep them on your machine.

How to access my local dev server?

You can run your npm run dev as usual. Nothhing special is required by you. mkenv will magically make sure that when you access localhost:3000 from browser or postman or anything else you will be routed to the proper container and to the proper process.

FAQ

Can I use this on Linux or Windows?

Not officially yet. Linux support is near-term; Windows likely rides on WSL once the experience doesn't suck.

Does mkenv replace Docker Desktop?

No, it depends on Docker for virtualization. Think of mkenv as the paranoid orchestrator on top.

Where is the cache stored?

By default under ~/Library/Caches/mkenv with subfolders per project fingerprint. Use mkenv list --verbose to inspect.

What happens if the container dies?

Run mkenv . again. You'll either reattach or get a fresh container using existing caches.

Is this meant for production workloads?

No. It's a dev tool for local workstations, not a deployment platform. If you push it to prod, that's on you.

Can I keep my editor outside the container?

Sure, but the safer move is to run Cursor/VS Code inside via the --editor flag so AI agents stay sandboxed.

Is there telemetry?

No analytics pings. If something breaks, file an issue rather than letting logs spy on you.