cubbi/CHANGELOG.md

CHANGELOG

v0.5.0 (2025-12-15)

Bug Fixes

• Crush providers configuration (#30, a709071)

• Cubbi configure not working when configuring other provider (#32, 310149d)

• Ensure Docker containers are always removed when closing sessions (#35, b788f3f)

When closing sessions with already-stopped containers, the stop/kill operation would raise an exception, preventing container.remove() from being called. This left stopped containers in Docker even though they were removed from cubbi's session tracking.

The fix wraps stop/kill operations in their own try-except block, allowing the code to always reach container.remove() regardless of whether the container was already stopped.

• Make groupadd optional (group already may exist, like gid 20 from osx) (407c1a1)

• Prevent concurrent YAML corruption in sessions (#36, 10d9e9d)

fix: add file locking to prevent concurrent YAML corruption in sessions

When multiple cubbi instances run simultaneously, they can corrupt the sessions.yaml file due to concurrent writes. This manifests as malformed YAML entries (e.g., "status: running\ning2dc3ff11:").

This commit adds: - fcntl-based file locking for all write operations - Read-modify-write pattern that reloads from disk before each write - Proper lock acquisition/release via context manager

All write operations (add_session, remove_session, save) now: 1. Acquire exclusive lock on sessions.yaml 2. Reload latest state from disk 3. Apply modifications 4. Write atomically to file 5. Update in-memory cache 6. Release lock

This ensures that concurrent cubbi instances can safely modify the sessions file without corruption.

• Remove container even if already removed (a668437)

• Remove persistent_configs of images (#28, e4c64a5)

Documentation

• Update README with --no-cache and local MCP server documentation (3795de1)

• Added documentation for the new --no-cache flag in image build command - Added documentation for local MCP server support (add-local command) - Updated MCP server types to include local MCP servers - Added examples for all three types of MCP servers (Docker, Remote, Local)

Features

• Add --no-cache option to image build command (be171cf)

Added a --no-cache flag to 'cubbi image build' command to allow building Docker images without using the build cache, useful for forcing fresh builds.

• Add local MCP server support (b9cffe3)

• Add LocalMCP model for stdio-based MCP servers - Implement add_local_mcp() method in MCPManager - Add 'mcp add-local' CLI command with args and env support - Update cubbi_init.py MCPConfig with command, args, env fields - Add local MCP support in interactive configure tool - Update image plugins (opencode, goose, crush) to handle local MCPs - OpenCode: Maps to "local" type with command array - Goose: Maps to "stdio" type with command/args - Crush: Maps to "stdio" transport type

Local MCPs run as stdio-based commands inside containers, allowing users to integrate local MCP servers without containerization.

• Add opencode state/cache to persistent_config (#27, b7b78ea)

• Comprehensive configuration system and environment variable forwarding (#29, bae951c)

• feat: migrate container configuration from env vars to YAML config files

• Replace environment variable-based configuration with structured YAML config files - Add Pydantic models for type-safe configuration management in cubbi_init.py - Update container.py to generate /cubbi/config.yaml and mount into containers - Simplify goose plugin to extract provider from default model format - Remove complex environment variable handling in favor of direct config access - Maintain backward compatibility while enabling cleaner plugin architecture

• feat: optimize goose plugin to only pass required API key for selected model

• Update goose plugin to set only the API key for the provider of the selected model - Add selective API key configuration for anthropic, openai, google, and openrouter - Update README.md with comprehensive automated testing documentation - Add litellm/gpt-oss:120b to test.sh model matrix (now 5 images × 4 models = 20 tests) - Include single prompt command syntax for each tool in the documentation

• feat: add comprehensive integration tests with pytest parametrization

• Create tests/test_integration.py with parametrized tests for 5 images × 4 models (20 combinations)
  • Add pytest configuration to exclude integration tests by default - Add integration marker for selective test running - Include help command tests and image availability tests - Document test usage in tests/README_integration.md

Integration tests cover: - goose, aider, claudecode, opencode, crush images - anthropic/claude-sonnet-4-20250514, openai/gpt-4o, openrouter/openai/gpt-4o, litellm/gpt-oss:120b models - Proper command syntax for each tool - Success validation with exit codes and completion markers

Usage: - pytest (regular tests only) - pytest -m integration (integration tests only) - pytest -m integration -k "goose" (specific image)

• feat: update OpenCode plugin with perfect multi-provider configuration

• Add global STANDARD_PROVIDERS constant for maintainability - Support custom providers (with baseURL) vs standard providers - Custom providers: include npm package, name, baseURL, apiKey, models - Standard providers: include only apiKey and empty models - Use direct API key values from cubbi config instead of env vars - Only add default model to the provider that matches the default model - Use @ai-sdk/openai-compatible for OpenAI-compatible providers - Preserve model names without transformation - All providers get required empty models{} section per OpenCode spec

This ensures OpenCode can properly recognize and use both native providers (anthropic, openai, google, openrouter) and custom providers (litellm, etc.) with correct configuration format.

• refactor: model is now a combination of provider/model

• feat: add separate integration test for Claude Code without model config

Claude Code is Anthropic-specific and doesn't require model selection like other tools. Created dedicated test that verifies basic functionality without model preselection.

• feat: update Claude Code and Crush plugins to use new config system

• Claude Code plugin now uses cubbi_config.providers to get Anthropic API key - Crush plugin updated to use cubbi_config.providers for provider configuration - Both plugins maintain backwards compatibility with environment variables - Consistent plugin structure across all cubbi images

• feat: add environments_to_forward support for images

• Add environments_to_forward field to ImageConfig and Image models - Update container creation logic to forward specified environment variables from host - Add environments_to_forward to claudecode cubbi_image.yaml to ensure Anthropic API key is always available - Claude Code now gets required environment variables regardless of model selection - This ensures Claude Code works properly even when other models are specified

Fixes the issue where Claude Code couldn't access Anthropic API key when using different model configurations.

• refactor: remove unused environment field from cubbi_image.yaml files

The 'environment' field was loaded but never processed at runtime. Only 'environments_to_forward' is actually used to pass environment variables from host to container.

Cleaned up configuration files by removing: - 72 lines from aider/cubbi_image.yaml - 42 lines from claudecode/cubbi_image.yaml - 28 lines from crush/cubbi_image.yaml - 16 lines from goose/cubbi_image.yaml - Empty environment: [] from opencode/cubbi_image.yaml

This makes the configuration files cleaner and only contains fields that are actually used by the system.

• feat: implement environment variable forwarding for aider

Updates aider to automatically receive all relevant environment variables from the host, similar to how opencode works.

Changes: - Added environments_to_forward field to aider/cubbi_image.yaml with comprehensive list of API keys, configuration, and proxy variables - Updated aider_plugin.py to use cubbi_config system for provider/model setup - Environment variables now forwarded automatically during container creation - Maintains backward compatibility with legacy environment variables

Environment variables forwarded: - API Keys: OPENAI_API_KEY, ANTHROPIC_API_KEY, DEEPSEEK_API_KEY, etc. - Configuration: AIDER_MODEL, GIT_* variables, HTTP_PROXY, etc. - Timezone: TZ for proper log timestamps

Tested: All aider tests pass, environment variables confirmed forwarded.

• refactor: remove unused volumes and init fields from cubbi_image.yaml files

Both 'volumes' and 'init' fields were loaded but never processed at runtime. These were incomplete implementations that didn't affect container behavior.

Removed from all 5 images: - volumes: List with mountPath: /app (incomplete, missing host paths) - init: pre_command and command fields (unused during container creation)

The cubbi_image.yaml files now only contain fields that are actually used: - Basic metadata (name, description, version, maintainer, image) - persistent_configs (working functionality) - environments_to_forward (working functionality where present)

This makes the configuration files cleaner and eliminates confusion about what functionality is actually implemented.

• refactor: remove unused ImageInit and VolumeMount models

These models were only referenced in the Image model definition but never used at runtime since we removed all init: and volumes: fields from cubbi_image.yaml files.

Removed: - VolumeMount class (mountPath, description fields) - ImageInit class (pre_command, command fields) - init: Optional[ImageInit] field from Image model - volumes: List[VolumeMount] field from Image model

The Image model now only contains fields that are actually used: - Basic metadata (name, description, version, maintainer, image) - environment (loaded but unused - kept for future cleanup) - persistent_configs (working functionality) - environments_to_forward (working functionality)

This makes the data model cleaner and eliminates dead code.

• feat: add interactive configuration command

Adds cubbi configure command for interactive setup of LLM providers and models through a user-friendly questionnaire interface.

New features: - Interactive provider configuration (OpenAI, Anthropic, OpenRouter, etc.) - API key management with environment variable references - Model selection with provider/model format validation - Default settings configuration (image, ports, volumes, etc.) - Added questionary dependency for interactive prompts

Changes: - Added cubbi/configure.py with full interactive configuration logic - Added configure command to cubbi/cli.py - Updated uv.lock with questionary and prompt-toolkit dependencies

Usage: cubbi configure

• refactor: update integration tests for current functionality

Updates integration tests to reflect current cubbi functionality:

test_integration.py: - Simplified image list (removed crush temporarily) - Updated model list with current supported models - Removed outdated help command tests that were timing out - Simplified claudecode test to basic functionality test - Updated command templates for current tool versions

test_integration_docker.py: - Cleaned up container management tests - Fixed formatting and improved readability - Updated assertion formatting for better error messages

These changes align the tests with the current state of the codebase and remove tests that were causing timeouts or failures.

• fix: fix temporary file chmod

• Dynamic model management for OpenAI-compatible providers (#33, 7d6bc5d)

feat: add models fetch for openai-compatible endpoint

• Universal model management for all standard providers (#34, fc819a3)

• fix: add crush plugin support too

• feat: comprehensive model management for all standard providers

• Add universal provider support for model fetching (OpenAI, Anthropic, Google, OpenRouter) - Add default API URLs for standard providers in config.py - Enhance model fetcher with provider-specific authentication: * Anthropic: x-api-key header + anthropic-version header * Google: x-goog-api-key header + custom response format handling * OpenAI/OpenRouter: Bearer token (unchanged) - Support Google's unique API response format (models vs data key, name vs id field) - Update CLI commands to work with all supported provider types - Enhance configure interface to include all providers (even those without API keys) - Update both OpenCode and Crush plugins to populate models for all provider types - Add comprehensive provider support detection methods

Refactoring

• Deep clean plugins (#31, 3a7b921)

• refactor: deep clean plugins

• refactor: modernize plugin system with Python 3.12+ typing and simplified discovery

• Update typing to Python 3.12+ style (Dict->dict, Optional->union types) - Simplify plugin discovery using PLUGIN_CLASS exports instead of dir() reflection - Add public get_user_ids() and set_ownership() functions in cubbi_init - Add create_directory_with_ownership() helper method to ToolPlugin base class - Replace initialize() + integrate_mcp_servers() pattern with unified configure() - Add is_already_configured() checks to prevent overwriting existing configs - Remove excessive comments and clean up code structure - All 5 plugins updated: goose, opencode, claudecode, aider, crush

• fix: remove duplicate

v0.4.0 (2025-08-06)

Documentation

• Update readme (#25, 9dc1158)

doc: update readme

Features

• Add user port support (#26, 75c9849)

• feat: add user port support

• fix: fix unit test and improve isolation

• refactor: remove some fixture

• Make opencode beautiful by default (#24, b8ecad6)

opencode: try having compatible default theme

• Support for crush (#23, 472f030)

v0.3.0 (2025-07-31)

Bug Fixes

• Claudecode and opencode arm64 images (#21, dba7a7c)

• Update readme (4958b07)

Continuous Integration

• Remove conventional commit, as only PR is required (afae8a1)

Features

• Add --mcp-type option for remote MCP servers (d41faf6)

Auto-detects connection type from URL (/sse -> sse, /mcp -> streamable_http) or allows manual specification. Updates goose plugin to use actual MCP type instead of hardcoded sse.

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

• Add Claude Code image support (#16, b28c2bd)

• feat: add Claude Code image support

Add a new Cubbi image for Claude Code (Anthropic's official CLI) with: - Full Claude Code CLI functionality via NPM package - Secure API key management with multiple authentication options - Enterprise support (Bedrock, Vertex AI, proxy configuration) - Persistent configuration and cache directories - Comprehensive test suite and documentation

The image allows users to run Claude Code in containers with proper isolation, persistent settings, and seamless Cubbi integration. It gracefully handles missing API keys to allow flexible authentication.

Also adds optional Claude Code API keys to container.py for enterprise deployments.

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

• Pre-commit fixes

---

Co-authored-by: Claude noreply@anthropic.com

Co-authored-by: Your Name you@example.com

• Add configuration override in session create with --config/-c (672b8a8)

• Add MCP tracking to sessions (#19, d750e64)

Add mcps field to Session model to track active MCP servers and populate it from container labels in ContainerManager. Enhance MCP remove command to warn when removing servers used by active sessions.

🤖 Generated with Claude Code

Co-authored-by: Claude noreply@anthropic.com

• Add network filtering with domain restrictions (#22, 2eb15a3)

• fix: remove config override logging to prevent API key exposure

• feat: add network filtering with domain restrictions

• Add --domains flag to restrict container network access to specific domains/ports - Integrate monadicalsas/network-filter container for network isolation - Support domain patterns like 'example.com:443', '*.api.com' - Add defaults.domains configuration option - Automatically handle network-filter container lifecycle - Prevent conflicts between --domains and --network options

• docs: add --domains option to README usage examples

• docs: remove wildcard domain example from --domains help

Wildcard domains are not currently supported by network-filter

• Add ripgrep and openssh-client in images (#15, e70ec35)

• Add sudo and sudoers (#20, 9c8ddbb)

• feat: add sudo and sudoers

• Update cubbi/images/cubbi_init.py

Co-authored-by: pr-agent-monadical[bot] <198624643+pr-agent-monadical[bot]@users.noreply.github.com>

---

• Implement Aider AI pair programming support (#17, fc0d6b5)

• feat: implement Aider AI pair programming support

• Add comprehensive Aider Docker image with Python 3.12 and system pip installation - Implement aider_plugin.py for secure API key management and environment configuration - Support multiple LLM providers: OpenAI, Anthropic, DeepSeek, Gemini, OpenRouter - Add persistent configuration for ~/.aider/ and ~/.cache/aider/ directories - Create comprehensive documentation with usage examples and troubleshooting - Include automated test suite with 6 test categories covering all functionality - Update container.py to support DEEPSEEK_API_KEY and GEMINI_API_KEY - Integrate with Cubbi CLI for seamless session management

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

• Fix pytest for aider

• Fix pre-commit

---

Co-authored-by: Your Name you@example.com

• Include new image opencode (#14, 5fca51e)

• feat: include new image opencode

• docs: update readme

• Support config openai.url for goose/opencode/aider (da5937e)

Refactoring

• New image layout and organization (#13, e5121dd)

• refactor: rework how image are defined, in order to create others wrapper for others tools

• refactor: fix issues with ownership

• refactor: image share now information with others images type

• fix: update readme

v0.2.0 (2025-05-21)

Continuous Integration

• Add semantic release configuration (and use pyproject version) (fbba8b7)

• Try fixing the dynamic_import issue (252d8be)

• Try fixing the dynamic_import issue (2, force adding pyproject.toml) (31e09bc)

Documentation

• Add information for uvx (ba852d5)

• Add mit license (13c896a)

• Update classifiers (5218bb1)

• Update README (15d86d2)

Features

• cubbix: Add --no-shell in combination with --run to not drop a shell and exit when the command is done (75daccb)

v0.1.0-rc.1 (2025-04-18)

Bug Fixes

• Mcp tests (3799f04)

• Osx tests on volume (7fc9cfd)

• Remove double connecting to message (e36f454)

• Remove the "mc stop" meant to be in the container, but not implemented (4f54c0f)

• cli: Rename MAI->MC (354834f)

• goose: Add ping, nano and vim to the default image (028bd26)

• goose: Always update the file (b1aa415)

• goose: Ensure configuration is run as user (cfa7dd6)

• goose: Install latest goose version, do not use pip (7649173)

• goose: Remove MCP_HOST and such, this is not how mcp works (d42af87)

• goose: Rename mai to mc, add initialization status (74c723d)

• langfuse: Fix goose langfuse integration (wrong env variables) (e36eef4)

• mc: Fix runtime issue when starting mc (6f08e2b)

• mcp: Fix UnboundLocalError: cannot access local variable 'container_name' where it is not associated with a value (deff036)

• session: Ensure a session connect only to the mcp server passed in --mcp (5d674f7)

• session: Fix session status display (092f497)

• ssh: Do not enable ssh automatically (f32b3dd)

• uid: Correctly pass uid/gid to project (e25e30e)

• uid: Use symlink instead of volume for persistent volume in the container (a74251b)

Chores

• Remove unnecessary output (30c6b99)

• Update doc and add pre-commit (958d87b)

Continuous Integration

• Add ci files (#11, 3850bc3)

• ci: add ci files

• fix: add goose image build

Documentation

• Add --run option examples to README (6b2c1eb)

• Prefer mcx alias in README examples (9c21611)

• mcp: Add specification for MCP server support (20916c5)

• readme: Remove license part (1c538f8)

• readme: Update README to update tool call (a4591dd)

Features

• First commit (fde6529)

• cli: Auto connect to a session (4a63606)

• cli: Auto mount current directory as /app (e6e3c20)

• cli: More information when closing session (08ba1ab)

• cli: Phase 1 - local cli with docker integration (6443083)

• cli: Separate session state into its own session.yaml file (7736573)

• cli: Support to join external network (133583b)

• config: Add global user configuration for the tool (dab783b)

• langfuse - default driver - and api keys

• config: Ensure config is correctly saved (deb5945)

• gemini: Support for gemini model (2f9fd68)

• goose: Auto add mcp server to goose configuration when starting a session (7805aa7)

• goose: Optimize init status (16f59b1)

• goose: Update config using uv script with pyyaml (#6, 9e742b4)

• keys: Pass local keys to the session by default (f83c49c)

• llm: Add default model/provider to auto configure the driver (#7, 5b9713d)

• mc: Support for uid/gid, and use default current user (a51115a)

• mcp: Add inspector (d098f26)

• mcp: Add the possibility to have default mcp to connect to (4b0461a)

• mcp: Ensure inner mcp environemnt variables are passed (0d75bfc)

• mcp: First docker proxy working (0892b6c)

• mcp: Improve inspector reliability over re-run (3ee8ce6)

• mcp: Initial version of mcp (212f271)

• project: Explicitely add --project to save information in /mc-config across run. (3a182fd)

Containers are now isolated by default.

• run: Add --run command (33d90d0)

• ssh: Make SSH server optional with --ssh flag (5678438)

• Added --ssh flag to session create command - Modified mc-init.sh to check MC_SSH_ENABLED environment variable - SSH server is now disabled by default - Updated README.md with new flag example - Fixed UnboundLocalError with container_name in exception handler

• volume: Add mc config volume command (2caeb42)

• volume: Add the possibilty to mount local directory into the container (like docker volume) (b72f1ee)

Refactoring

• Move drivers directory into mcontainer package (307eee4)

• Relocate goose driver to mcontainer/drivers/ - Update ConfigManager to dynamically scan for driver YAML files - Add support for mc-driver.yaml instead of mai-driver.yaml - Update Driver model to support init commands and other YAML fields - Auto-discover drivers at runtime instead of hardcoding them - Update documentation to reflect new directory structure

• Reduce amount of data in session.yaml (979b438)

• Rename driver to image, first pass (51fb79b)

• Rename project to cubbi (12d77d0)

Testing

• Add unit tests (7c46d66)