ctenv 0.6

ctenv is a tool for running in containers as current user

ctenv

Container environment as current user, in any image, preserving user identity.

Start container based on any image, with current directory mounted and runs as your own user in the container. Run a command or start an interactive shell.

Install

# Install with pip
$ pip install ctenv

# Install with uv
$ uv tool install ctenv

# Or run directly without installing
$ uv tool run ctenv --help

Recommend installing uv.

Usage

# Interactive shell in ubuntu container
$ ctenv run --image ubuntu -- bash

# Run specific command
$ ctenv run -- npm test

# Run Claude Code in a container
$ ctenv run --image node:20 --volume ~/.claude.json --volume ~/.claude \
    --post-start-command "npm install -g @anthropic-ai/claude-code"

Why ctenv?

When running containers with mounted directories, files created inside often have root ownership or wrong permissions. ctenv solves this by:

• Creating a matching user (same UID/GID) dynamically in existing images at runtime
• Mounting your current directory with correct permissions
• Using gosu to drop privileges after container setup

This works with any existing Docker image without modification - no custom Dockerfiles needed. Provides similar functionality to Podman's --userns=keep-id but works with Docker. Also similar to Development Containers but focused on running individual commands rather than persistent development environments.

Under the hood, ctenv starts containers as root for file ownership setup, then drops privileges using bundled gosu binaries before executing your command. It generates bash entrypoint scripts dynamically to handle user creation and environment setup.

Highlights

• Works with existing images without modifications
• Files created have your UID/GID (preserves permissions)
• Convenient volume mounting like -v ~/.gitconfig (mounts to same path in container)
• Simple configuration with reusable .ctenv.toml setups

Requirements

• Python 3.10+
• Docker (tested on Linux/macOS)

Features

• User identity preservation (matching UID/GID in container)
• Volume mounting with shortcuts like -v ~/.gitconfig (mounts to same path)
• Volume ownership fixing with custom :chown option (similar to Podman's :U and :chown)
• Post-start commands for running setup as root before dropping to user permissions
• Template variables with environment variables, like ${env.HOME}
• Configuration file support with reusable container definitions
• Cross-platform support for linux/amd64 and linux/arm64 containers
• Bundled gosu binaries for privilege dropping
• Interactive and non-interactive command execution

Configuration

Create .ctenv.toml for reusable container setups:

[defaults]
command = "zsh"

[containers.python]
image = "python:3.11"
volumes = ["~/.cache/pip"]

# For running Claude Code in container
[containers.claude]
image = "node:20"
post_start_commands = ["npm install -g @anthropic-ai/claude-code"]
volumes = ["~/.claude.json", "~/.claude"]

Then run:

$ ctenv run python -- python script.py
$ ctenv run claude

Common Use Cases

Claude Code

Run Claude Code in a container for isolation:

$ ctenv run --image node:20 -v ~/.claude.json -v ~/.claude/ --post-start-command "npm install -g @anthropic-ai/claude-code" -- claude

Or write as config in ~/.ctenv.toml:

[containers.claude]
image = "node:20"
volumes = ["~/.claude.json", "~/.claude/"]
post_start_commands = ["npm install -g @anthropic-ai/claude-code"]
command = "claude"

and use with: ctenv run claude

You can also use Dev Containers for Claude Code: https://docs.anthropic.com/en/docs/claude-code/devcontainer

Development Tools

Run linters, formatters, or compilers from containers:

$ ctenv run --image rust:latest -- cargo fmt
$ ctenv run --image node:20 -- eslint src/

Build Systems

Use containerized build environments:

[containers.build]
image = "some-build-system:v17"
volumes = ["build-cache:/var/cache:rw,chown"]

Detailed Examples

Claude Code without installing every time

The most obvious way is to create a container image where you have installed Claude Code and run ctenv using that image.

[containers.claude]
image = "my-dev-image"
volumes = ["~/.claude.json", "~/.claude/"]
command = "claude"

One alternative is to use NVM and store the installation in a volume. Below is example just to showcase the NVM "hack". For real use, you likely want an image with more development tools installed.

In .ctenv.toml:

# Installing in volume called claude-nvm
[containers.claude-install]
image = "ubuntu:latest"
volumes = ["~/.claude.json", "~/.claude/", "claude-nvm:/nvm"]
env = ["NVM_DIR=/nvm"]
post_start_commands = [
    # Install curl (for nvm)
    "apt update && apt install -y curl",
    # Install nvm
    "curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash",
    # node and claude code
    "/bin/bash -c 'source /nvm/nvm.sh && nvm install 20 && npm install -g @anthropic-ai/claude-code'"
]
command = "exit 0"

# Running
[containers.claude-run]
image = "ubuntu:latest"
volumes = ["~/.claude.json", "~/.claude/", "claude-nvm:/nvm"]
env = ["NVM_DIR=/nvm"]
command = "/bin/bash -c 'source /nvm/nvm.sh && claude'"

Run:

# Install (once)
$ ctenv run claude-install

# Run without installing again
$ ctenv run claude-run

Claude Code with Network Restrictions

For running Claude Code in isolation with network limitations:

[containers.claude]
image = "node:20"
network = "bridge"
run_args = ["--cap-add=NET_ADMIN"]
post_start_commands = [
    "apt update && apt install -y iptables",
    "iptables -A OUTPUT -d 192.168.0.0/24 -j DROP",
    "npm install -g @anthropic-ai/claude-code"
]
volumes = ["~/.claude.json", "~/.claude"]

Note: On macOS, Claude Code stores credentials in the keychain by default. When run in a container, it will create ~/.claude/.credentials.json instead, which persists outside the container due to the volume mount.

Build System with Caching

Complex build environment with shared caches:

[containers.build]
image = "registry.company.internal/build-system:v1"
env = [
    "BB_NUMBER_THREADS",
    "CACHE_MIRROR=http://build-cache.company.internal/",
    "BUILD_CACHES_DIR=/var/cache/build-caches/image-${image|slug}",
]
volumes = [
    "build-caches-user-${env.USER}:/var/cache/build-caches:rw,chown",
    "${env.HOME}/.ssh:/home/builduser/.ssh:ro"
]
post_start_commands = ["source /venv/bin/activate"]

This setup ensures the build environment matches the user's environment while sharing caches between different repository clones.

History

The background for ctenv was a bash script that I developed at work (Agama) for running our build system in a container. Besides running the build, it was useful to also be able to run and use the compiled code in the build system environment, which had older libraries than the modern OSes that was used by the developers.

ctenv is a much more generic tool than that bash script and without the many hard-coded parts. Written i Python and support for config files and much more.