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 developers who would rather delete a container than reimage their laptop.

This documentation covers how to install, run, and configure mkenv. No YAML files required.

Installation

Prerequisites

• macOS 12+ / Linux (arm64 or amd64) / Windows 10+ with WSL2.
• Docker Desktop 4.x or Docker Engine with virtualization enabled.
• Terminal basics (zsh/bash) and permissions to install binaries to $PATH.

macOS (Homebrew)

brew tap 0xa1bed0/mkenv
brew install mkenv

Linux / Windows (WSL)

# Download the binary (arm64 or amd64)
curl -L https://github.com/0xa1bed0/mkenv/releases/latest/download/mkenv-linux-arm64 -o mkenv
# or for amd64: curl -L https://github.com/0xa1bed0/mkenv/releases/latest/download/mkenv-linux-amd64 -o mkenv

# Make it executable and move to PATH
chmod +x mkenv
sudo mv mkenv /usr/local/bin/

Verify Installation

mkenv version

Important: Ensure Docker is running before launching containers.

Quickstart

1. Navigate to your project directory: cd /path/to/your/project
2. Run: mkenv .
3. mkenv analyzes your project, builds a Docker image, and drops you into a container shell
4. You're now inside a sandboxed environment with all detected tools installed

First run: Builds the full image and caches dependencies (slower)

Subsequent runs: Reuse cached layers for fast startup

.mkenv Configuration Files

While mkenv works with zero configuration, you can customize behavior using .mkenv files. These files provide the same options as command-line flags.

Example: Organization-wide Defaults

Create ~/projects/.mkenv to apply settings to all projects in that directory:

{
  "enabled_bricks": ["codex", "nvim", "tmux"]
}

Example: Project-specific Settings

Create .mkenv in your project root:

{
  "enabled_bricks": ["claude-code"],
  "volumes": ["~/datasets:/data"]
}

Example: Install Additional System Packages

Create .mkenv in your project root:

{
  "extra_pkgs": ["git", "curl", "vim", "htop", "jq"]
}

These packages will be installed via the system's package manager (e.g., apt-get on Debian-based systems).

Example: Custom Environment Variables (with secrets)

Inject environment variables into the container. Literal values are passed through; values prefixed with mkenv_value_from:<path> are read from a host file at container start.

{
  "envs": {
    "API_BASE":  "https://api.example.com",
    "API_TOKEN": "mkenv_value_from:~/secrets/api-token",
    "DEPLOY_KEY": "mkenv_value_from:/home/me/.config/myapp/deploy.key"
  }
}

Secret values resolved via mkenv_value_from: are never baked into the docker image and never logged — they are injected at container creation time and live only for the lifetime of the container.

Security guarantees for mkenv_value_from::

• Paths must be absolute or ~/-prefixed. Relative paths are rejected.
• Symlinks are fully resolved, then checked against the same guardrails that protect mounts — you cannot read from ~/.ssh, ~/.aws, ~/.gnupg, /etc, /proc, browser/password-manager directories, or any other protected path. Symlink-escape attempts are blocked post-resolution.
• Only regular files are accepted (no FIFOs, devices, sockets, or directories).
• File size is capped at 1 MiB.
• NUL bytes in paths, names, or content cause an error rather than a cryptic docker failure.
• Exactly one trailing newline (\n or \r\n) is trimmed; internal newlines are preserved so multi-line values such as PEM keys work.
• World/group-readable files print a warning prompting you to chmod 600.
• If any env in the map fails resolution, the container does not start — there is no partial-env mode.

Reserved names: the MKENV_ prefix is reserved for mkenv-internal variables, and loader-hijack names (LD_PRELOAD, LD_LIBRARY_PATH, LD_AUDIT, DYLD_INSERT_LIBRARIES, DYLD_LIBRARY_PATH, DYLD_FALLBACK_LIBRARY_PATH) are blocked.

Note: custom envs are applied at container-run time, not at image-build time. Changing an envs entry does not trigger a rebuild — restart the container to pick up the new value.

How It Works

• mkenv walks up from your project directory to the filesystem root
• All .mkenv files found are loaded and merged (root → project)
• Child configs override parent configs
• Command-line flags override all .mkenv files

Available Fields

Use cases: Set organization-wide defaults, team preferences, or project-specific requirements without repeating command flags.

LLM Support

Run AI coding tools safely inside mkenv containers using the --tools flag.

Example: Install Claude Code

mkenv . --tools claude-code

Available LLM Tools

• claude-code — Anthropic's Claude Code CLI
• codex — OpenAI's Codex CLI

Usage

# Start container with Claude Code
mkenv . --tools claude-code

# Inside the container, run Claude
claude

Security Isolation

AI tools run inside the container with restricted access:

• Can only access your project directory
• Cannot access ~/.ssh, ~/.aws, ~/.config, or other credentials
• All AI-generated commands run inside the container, not on your host
• Deleting the container removes all AI-generated changes outside your project folder

Combining Tools

Install multiple tools at once:

mkenv . --tools claude-code,nvim,tmux

Other available tools: nvim, tmux, pulumi, ansible

GPG Agent Forwarding (YubiKey / Smartcard)

If you use a YubiKey or smartcard with GPG, you can forward your host's GPG agent into the mkenv container. This lets you use YubiKey-backed SSH authentication, GPG signing, and file encryption/decryption inside the sandbox — just like on your host, without exposing your keys.

Usage

mkenv . --mount-gpg

Or set it permanently in your project's .mkenv file:

{
  "mount_gpg": true
}

How It Works

mkenv does three things when you pass --mount-gpg:

1. Socket forwarding — creates a local proxy for your GPG agent sockets and forwards all GPG and SSH agent traffic to the host agent. Your private keys never leave the host.
2. Keyring import — exports your public keys and trust database from the host (gpg --export) and imports them into the container. This works across all GPG versions (2.2 with kbx, 2.4+ with keyboxd). Private key stubs (smartcard references, no secret material) are also copied so GPG knows which keys live on your YubiKey.
3. Pinentry management — when an SSH sign request requires your YubiKey PIN, the proxy automatically pauses the container terminal, lets your pinentry program render cleanly, and resumes after you enter the PIN.

The result: gpg --list-secret-keys, gpg --encrypt, gpg --decrypt, gpg --sign, and SSH all work inside the container exactly as they do on your host.

Prerequisites

• GPG agent running on the host with SSH support enabled (enable-ssh-support in gpg-agent.conf)
• YubiKey or smartcard configured for GPG/SSH
• On macOS: GPG Suite or Homebrew gnupg with gpg-agent running

PIN Entry Setup

Before launching mkenv, tell the GPG agent which terminal to use for PIN prompts:

# Run this in the same terminal where you'll launch mkenv
gpg-connect-agent updatestartuptty /bye

Tip: Add an alias to your shell config to make this easier:

# In ~/.zshrc or ~/.bashrc
alias gpghere="gpg-connect-agent updatestartuptty /bye"

Then just run gpghere before mkenv.

Supported Pinentry Programs

All pinentry programs work with --mount-gpg:

• pinentry-tty — plain text prompt, no curses rendering, works well in shared terminal environments
• pinentry-curses — TUI box with ncurses, renders cleanly when mkenv pauses the terminal
• pinentry-mac — native macOS dialog, fully independent of the terminal

Example Workflow

# Terminal setup
gpghere

# Launch mkenv with GPG forwarding
mkenv . --mount-gpg

# Inside the container — SSH uses your YubiKey automatically
ssh root@your-server.com
# → PIN prompt appears on the host
# → Enter PIN, press Enter
# → SSH session opens

# Encryption/decryption works too
gpg --encrypt -r your@email.com secrets.env
gpg --decrypt secrets.env.gpg
# → YubiKey touch/PIN prompt on the host

# Signing
gpg --sign --armor message.txt

Combining with Ansible

For infrastructure automation with YubiKey-backed SSH:

mkenv . --mount-gpg --tools ansible

This gives you a sandboxed environment where Ansible can SSH to remote hosts using your YubiKey for authentication. Run playbooks, manage inventory, and use ansible-vault — all isolated from your host.

Ansible with PIN caching (default)

Most GPG agent configurations cache the PIN after the first entry (this is the default). Ansible works seamlessly — the first SSH connection prompts for your PIN, and subsequent parallel connections use the cached PIN without any terminal disruption.

Ansible without PIN caching / with touch-required YubiKey

If you've disabled PIN caching or configured your YubiKey to require a touch for every operation, each SSH connection needs a separate PIN entry or touch. Ansible opens multiple SSH connections in parallel by default, which can cause overlapping PIN prompts.

Use --forks 1 to serialize connections so each gets a clean PIN prompt:

ansible-playbook -i inventory.yml deploy.yml --forks 1

Alternatively, set forks = 1 in your ansible.cfg:

[defaults]
forks = 1

Ansible

Install Ansible inside your mkenv container for infrastructure automation:

mkenv . --tools ansible

This installs Ansible via pip along with its dependencies (python3, sshpass). All standard Ansible CLI tools are available: ansible, ansible-playbook, ansible-galaxy, ansible-vault, ansible-inventory, ansible-doc, etc.

Ansible's pip cache and ~/.ansible directory are persisted across container restarts.

Usage with GPG/YubiKey SSH

# Infrastructure automation with hardware-backed SSH keys
mkenv . --mount-gpg --tools ansible

# Inside the container
ansible-playbook -i inventory.yml deploy.yml

Ansible SSH connections will use your YubiKey for authentication — PIN prompts appear on your host terminal when needed.

Commands

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

One-off command execution (-c)

Run a single command inside the mkenv environment without opening an interactive shell. Useful for CI pipelines, git pre-commit hooks, and one-off builds where the runtimes are not installed on the host.

# Run a single command and exit
mkenv . -c "make precommit"

# Use in a git pre-commit hook
mkenv . -c "npm test"

# Exit code from the command propagates to the host
mkenv . -c "exit 42"; echo $?   # prints 42

• No interactive shell or TTY — stdout/stderr are streamed directly.
• No control plane or reverse proxy is started (shorter startup).
• Container is removed on exit, same as interactive mode.

mkenv attach

Open an additional shell in an already-running container for the same project.

mkenv attach [PATH]

• Automatically finds the running container for your project
• Useful for opening multiple terminal windows in the same sandbox

mkenv list

List all mkenv containers and their status.

mkenv list [--verbose]

• Shows project path, container ID, and status
• --verbose includes cache and volume details

mkenv clean

Remove containers and caches for a project.

mkenv clean [PATH] [--all]

• Without flags: cleans the current project only
• --all: removes all mkenv containers and caches

mkenv completion

Generate shell completion scripts.

mkenv completion [bash|zsh|fish]

Add the output to your shell config for tab completion.

mkenv help

Show help for commands.

mkenv help [command]

Configuration & Behavior

Automatic Language Detection

mkenv automatically detects your project's languages and tools by scanning for:

• Node.js: package.json, pnpm-lock.yaml, yarn.lock
• Python: requirements.txt, poetry.lock, Pipfile
• Go: go.mod
• Rust: Cargo.toml
• Ruby: Gemfile

Based on what it finds, mkenv installs the appropriate language runtimes, package managers, and language servers.

Security Defaults

• Containers run as a non-root user with restricted permissions
• Only your project directory is mounted (read-write) - no access to your home directory
• Shell history is sanitized to prevent credential leakage
• SSH keys and credentials are not accessible unless you explicitly mount them

Caching

mkenv caches dependencies using Docker volumes. First run builds everything, subsequent runs are fast. Rebuilds only happen when dependency files change.

Security Warnings

mkenv scans your project directory for sensitive files (SSH keys, tokens, credential files) before starting. If it detects anything suspicious, it will warn you and ask for confirmation.

Best practice: Never mount sensitive credentials into the container. Keep secrets on your host machine only. Remember that the container could be compromised by a supply chain attack.

Accessing Your Dev Server

Run your dev server normally inside the container:

npm run dev

mkenv automatically routes localhost:3000 (or any port) from your host machine to the container. Access it from your browser, Postman, or any other tool as usual.

How Port Forwarding Works

Unlike vanilla Docker or Devcontainers, you can't dynamically expose ports from inside a Docker environment — you need to think of exposed ports in advance. mkenv solves this with a bidirectional reverse proxy.

Architecture

┌──────────────────┐
│ Browser          │
│                  │
│ connects to      │
│  localhost:3000  │
└────┬─────────────┘
     │
     │           ┌──────────────────────┐
     │           │  mkenv host process  │    ┌──────────┐
     └────────────►                     │    │ Postgres │
                 │  Binds :3000, :5432  │────► :5432    │
                 │  on Mac on demand    │    └──────────┘
                 └───────────▲──────────┘
                             │
                             │
                     :45454 (fixed port)
           ┌─────────────────┼────────────────────┐
           │    Docker       │                    │
           │                 │                    │
           │    ┌────────────▼──────────────┐     │
           │    │    mkenv Container        │     │
           │    │                           │     │
           │    │  ┌──────────────────────┐ │     │
           │    │  │  Proxy Daemon        │ │     │
           │    │  │  :45454         :5432│ │     │
           │    │  └─────────┬──────────▲─┘ │     │
           │    │            │          │   │     │
           │    │            │          │   │     │
           │    │  ┌─────────▼──────────┼─┐ │     │
           │    │  │  npm run dev :3000 │ │ │     │
           │    │  │                    │ │ │     │
           │    │  │  connects to       │ │ │     │
           │    │  │  localhost:5432 ───┘ │ │     │
           │    │  └──────────────────────┘ │     │
           │    └───────────────────────────┘     │
           │                                      │
           └──────────────────────────────────────┘

The mkenv host process acts as a bidirectional traffic hub between your host and the container, using a fixed port (:45454) to avoid Docker's dynamic port limitation.

How Traffic Flows

• Browser → Container: Your browser accesses localhost:3000 → mkenv host process logs the request and forwards it to the proxy inside the container → Container proxy forwards to your dev server
• Container → Host: Your containerized app accesses localhost:5432 → if port is bound inside container, connects directly; otherwise routes through container proxy → mkenv host process → host service on that port

Key Points

• Ports are bound on demand — no manual configuration needed
• No additional daemons required — the host process starts with mkenv . and dies when you exit
• All connections are logged locally for audit
• Nothing leaves your laptop — all logging happens offline

Policies & Guardrails

mkenv includes a comprehensive policy engine that enforces security guardrails at multiple levels. Policies can be configured globally or per-project using a policy.json file.

Security Scanning

Secret Detection:

• Scans project files before creating containers
• Warns if secrets, SSH keys, or credentials are detected
• Requires explicit confirmation to proceed if sensitive files are found

Restricted Directories:

• Automatically blocks dangerous folders like ~/.ssh, ~/.aws, ~/.config from being mounted
• These restrictions cannot be overridden to prevent accidental credential exposure

Policy Configuration

Create a policy.json file in your mkenv config directory (typically ~/.mkenv/policy.json) to enforce organizational policies:

{
  "disabled_bricks": ["codex"],
  "enabled_bricks": ["nvim", "tmux"],
  "allowed_mount_paths": ["/home/user/projects", "/data"],
  "allowed_project_path": "/home/user/projects",
  "ignore_preferences": false,
  "reverse_proxy": {
    "denied_ports": [5432, 3306],
    "allowed_ports": []
  }
}

Policy Fields

Policy File Security

chmod 444 ~/.mkenv/policy.json

Reverse Proxy Security

mkenv allows containers to access host services (like databases) via a reverse proxy. The policy engine strictly controls which ports can be accessed.

Hardcoded Denied Ports (Always Blocked)

The following ports are permanently blocked and cannot be overridden by policy configuration:

• SSH & Remote Login: 22, 2222
• Remote Desktop: 3389 (RDP), 5900-5903 (VNC), 5800 (VNC/HTTP), 3283 (Apple Remote Desktop)
• File Sharing: 445 (SMB), 139 (NetBIOS), 2049 (NFS), 111 (rpcbind)
• Admin Panels: 80, 443, 8080, 8443, 9090 (common admin interfaces)
• Container Management: 2375-2377 (Docker), 6443, 8001, 10250, 10255 (Kubernetes)
• macOS Services: 548 (AFP), 631 (CUPS), 5353 (mDNS)
• Windows Services: 135 (RPC), 593 (RPC/HTTP), 1433-1434 (MS SQL), 3268-3269 (LDAP)

Custom Port Policies

{
  "reverse_proxy": {
    "denied_ports": [5432, 3306],
    "allowed_ports": [8000, 8080]
  }
}

• denied_ports - Additional ports to block beyond hardcoded list
• allowed_ports - Explicit allowlist (if set, only these ports are accessible, but hardcoded denials still apply)

Policy Enforcement

• All reverse proxy connections are checked against policy
• Denied connections are logged with source information
• All successful proxy connections are logged for auditing

Tool Control (Bricks)

Policies can control which tools (called "bricks") are available:

{
  "disabled_bricks": ["claude-code", "codex"],
  "enabled_bricks": ["nvim", "tmux", "pulumi"]
}

Use Cases:

• Block AI coding tools in security-sensitive environments
• Force-enable required development tools across teams
• Disable automatic detection and use explicit tool lists only

Volume Mount Restrictions

{
  "allowed_mount_paths": [
    "/home/user/projects",
    "/data/shared"
  ]
}

• If allowed_mount_paths is set, only directories under these paths can be mounted
• Empty list means "allow all" (except hardcoded blocked paths like ~/.ssh)
• Relative paths are resolved before checking
• Symlink targets are checked against policy

Project Path Restrictions

{
  "allowed_project_path": "/home/user/approved-projects"
}

• Restricts where mkenv can be run
• Useful for isolating work projects from personal projects
• Empty string means "allow all"

Example: Enterprise Policy

{
  "disabled_bricks": ["codex"],
  "enabled_bricks": ["nvim"],
  "allowed_project_path": "/work/projects",
  "allowed_mount_paths": ["/work"],
  "ignore_preferences": true,
  "reverse_proxy": {
    "denied_ports": [5432, 3306, 6379, 27017],
    "allowed_ports": []
  }
}

This policy:

• Blocks OpenAI Codex but allows Neovim
• Restricts mkenv to /work/projects directory only
• Prevents mounting anything outside /work
• Blocks access to common database ports from containers
• Ignores user preferences to enforce organizational standards

Example: Developer-Friendly Policy

{
  "disabled_bricks": [],
  "enabled_bricks": ["claude-code", "nvim", "tmux"],
  "reverse_proxy": {
    "denied_ports": [],
    "allowed_ports": []
  }
}

This policy:

• Allows all tools and auto-detection
• Pre-installs commonly used tools (Claude Code, Neovim, Tmux)
• Allows access to all non-hardcoded ports
• Still protects SSH, Docker, and other critical services (hardcoded denials)

FAQ

Can I use this on Linux or Windows?

Yes. Linux is fully supported (arm64 and amd64). Windows works via WSL2 using the Linux binary.

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?

In Docker volumes managed by mkenv. Use mkenv list --verbose to inspect cache details.

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?

Yes. You can connect VS Code or Cursor to the mkenv container using their remote development features. This keeps the editor UI on your host while running all commands inside the container.

Is there telemetry?

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

How do I git push?

Git operations (push, pull, clone) happen on your host machine where your credentials live. Everything else happens in the sandbox. This separates concerns: work runs isolated with no credentials, git operations run on host with credentials and no bloat.

How do I install packages that need sudo?

Use mkenv sandbox install <pkg> from inside the container. This is a controlled, audited way to install system packages. You can also specify packages in your .mkenv file with extra_pkgs.

What if auto-detection gets my project wrong?

Guide it with CLI options (--langs, --tools), a .mkenv file, or adjust ad-hoc with mkenv sandbox install.

IDE integration?

VS Code and Cursor can connect to mkenv containers using their remote development features. Dedicated plugins coming soon.

Can I use my YubiKey / smartcard inside the container?

Yes. Use --mount-gpg to forward your host's GPG agent into the container. SSH, GPG signing, encryption, and decryption all work — your public keyring is imported automatically and all crypto operations are forwarded to the host agent. Run gpg-connect-agent updatestartuptty /bye before launching mkenv so the agent knows where to show PIN prompts. See GPG Agent Forwarding for full details.

Can I use Ansible inside the container?

Yes. Use --tools ansible to install Ansible. Combine with --mount-gpg for YubiKey-backed SSH to remote hosts. See Ansible for details.