devs - DevContainer Management Tool

A Python command-line tool that simplifies managing multiple named devcontainers for any project.

Features

Multiple Named Containers: Start multiple devcontainers with custom names (e.g., "sally", "bob", "charlie")
VS Code Integration: Open containers in separate VS Code windows with clear titles
Project Isolation: Containers are prefixed with git repository names (org-repo format)
Environment Variable Management: Layered DEVS.yml configuration with user-specific overrides
Shared Authentication: Claude credentials are shared between containers for the same project
Cross-Platform: Works on any project with devcontainer configuration

Installation

pip install devs

Usage

# Start development environments
devs start frontend backend

# Open both in VS Code (separate windows)
devs vscode frontend backend

# Work in a specific container
devs shell frontend

# Run Claude in a container
devs claude frontend "Summarize this codebase"

# Run tests in a container
devs runtests frontend

# Environment variables support
devs start frontend --env DEBUG=true --env API_URL=http://localhost:3000
devs claude frontend "Fix the tests" --env NODE_ENV=test

# Set up Claude authentication (once per host)
devs claude --auth
# Or with API key
devs claude --auth --api-key <YOUR_API_KEY>

# Clean up when done
devs stop frontend backend

# List active containers
devs list

Configuration

Environment Variables

devs supports layered environment variable configuration through DEVS.yml files:

Priority order (highest to lowest):

CLI --env flags
~/.devs/envs/{org-repo}/DEVS.yml (user-specific project overrides)
~/.devs/envs/default/DEVS.yml (user defaults)
{project-root}/DEVS.yml (repository configuration)

Example DEVS.yml in your project:

env_vars:
  default:
    NODE_ENV: development
    API_URL: https://api.example.com
    DEBUG: "false"
  
  frontend:  # Container-specific overrides
    DEBUG: "true"
    FRONTEND_PORT: "3000"
    
  backend:
    NODE_ENV: production
    API_URL: https://prod-api.example.com

User-specific configuration:

# Global user defaults
mkdir -p ~/.devs/envs/default
echo 'env_vars:
  default:
    GLOBAL_SETTING: "user_preference"
    MY_SECRET: "user_secret"' > ~/.devs/envs/default/DEVS.yml

# Project-specific overrides (org-repo format)
mkdir -p ~/.devs/envs/myorg-myproject
echo 'env_vars:
  frontend:
    DEBUG: "true"
    LOCAL_SECRET: "dev_secret"' > ~/.devs/envs/myorg-myproject/DEVS.yml

📖 See ../../example-usage.md for detailed examples and scenarios

Requirements

Docker: Container runtime
VS Code: With code command in PATH
DevContainer CLI: npm install -g @devcontainers/cli
Project Requirements: .devcontainer/devcontainer.json in target projects

Architecture

Container Naming

Containers follow the pattern: dev-<org>-<repo>-<dev-name>

Example: dev-ideonate-devs-sally, dev-ideonate-devs-bob

VS Code Window Management

Each container gets unique workspace paths to ensure VS Code treats them as separate sessions.

The tool creates symlinks so all containers for the same project share Claude authentication.

Development

# Clone repository
git clone https://github.com/ideonate/devs.git
cd devs/python-devs

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black devs tests

# Type checking
mypy devs

License

MIT License

Metadata

Release files for devs-cli 6.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for devs-cli 6.0.0
File	Size	Uploaded
devs_cli-6.0.0.tar.gz	41.5 kB	Oct 7, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for devs-cli 6.0.0
File	Interpreter	ABI	Platform	Reset
devs_cli-6.0.0-py3-none-any.whl 21.0 kB Oct 7, 2026	Python 3	none	any	Details

Total release size: 62.5 kB

Release files / devs_cli-6.0.0.tar.gz

Download URL	devs_cli-6.0.0.tar.gz
Size	41.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`1e600daf6975cbe05fe771b535cf2adb743c8c9c3e40fdc69a4029531d34c52f`
BLAKE2b-256 checksum How to use checksums	`066b930ab4ffb82c6fc312fe4217784ba9c5741f764b561cfa479749a8e4f7d2`
Upload date	Oct 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/ideonate/devs
Publishing commit: github.com/ideonate/devs/tree/c19c00d5500037e2080719ee66ccadac24b3cecb

Workflow

Publishing configuration: github.com/ideonate/devs/blob/c19c00d5500037e2080719ee66ccadac24b3cecb/.github/workflows/bump-and-publish.yml
Publishing logs: github.com/ideonate/devs/actions/runs/37596853997/attempts/1

Artifact

Subject: devs_cli-6.0.0.tar.gz
SHA-256 checksum: 1e600daf6975cbe05fe771b535cf2adb743c8c9c3e40fdc69a4029531d34c52f Verifying attestations

Release files / devs_cli-6.0.0-py3-none-any.whl

Download URL	devs_cli-6.0.0-py3-none-any.whl
Size	21.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`41d6de559048757dccec893dd647165c96171e3b1a9c577e96e4449efb8d4198`
BLAKE2b-256 checksum How to use checksums	`d846ac6ae33244f5b7e4f1f64dc38ea3f112c06f4b6baaa52df3c7ac80d4bd93`
Upload date	Oct 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/ideonate/devs
Publishing commit: github.com/ideonate/devs/tree/c19c00d5500037e2080719ee66ccadac24b3cecb

Workflow

Publishing configuration: github.com/ideonate/devs/blob/c19c00d5500037e2080719ee66ccadac24b3cecb/.github/workflows/bump-and-publish.yml
Publishing logs: github.com/ideonate/devs/actions/runs/37596853997/attempts/1

Artifact

Subject: devs_cli-6.0.0-py3-none-any.whl
SHA-256 checksum: 41d6de559048757dccec893dd647165c96171e3b1a9c577e96e4449efb8d4198 Verifying attestations