mirror of
https://github.com/Monadical-SAS/cubbi.git
synced 2025-12-20 20:29:06 +00:00
Mathieu Virbel
bae951cf7c
* 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
441 lines
13 KiB
Markdown
441 lines
13 KiB
Markdown
<div align="center">
|
|
|
|
# Cubbi - Container Tool
|
|
|
|
Cubbi is a command-line tool for managing ephemeral containers that run AI tools and development environments, with support for MCP servers. It supports [Aider](https://github.com/Aider-AI/aider), [Crush](https://github.com/charmbracelet/crush), [Claude Code](https://github.com/anthropics/claude-code), [Goose](https://github.com/block/goose), [Opencode](https://github.com/sst/opencode).
|
|
|
|
|
|
|
|
[](https://github.com/monadical-sas/cubbi/actions/workflows/pytests.yml)
|
|
[](https://opensource.org/licenses/MIT)
|
|
|
|
</div>
|
|
|
|
## 🚀 Quick Reference
|
|
|
|
- `cubbi session create` - Create a new session
|
|
- `cubbix` - Shortcut for `cubbi session create`
|
|
- `cubbix .` - Mount the current directory
|
|
- `cubbix /path/to/dir` - Mount a specific directory
|
|
|
|
## 📋 Requirements
|
|
|
|
- [Docker](https://www.docker.com/)
|
|
- [uv](https://astral.sh/uv)
|
|
|
|
## 📥 Installation
|
|
|
|
```bash
|
|
# Via uv
|
|
uv tool install cubbi
|
|
|
|
# Without installation
|
|
# (meaning all commands below must be prefixed with `uvx`)
|
|
uvx cubbi
|
|
```
|
|
|
|
Then compile your first image:
|
|
|
|
```bash
|
|
cubbi image build goose
|
|
cubbi image build opencode
|
|
cubbi image build crush
|
|
```
|
|
|
|
### For Developers
|
|
|
|
If you are looking to contribute to the development, you will need to use `uv` as well:
|
|
|
|
```bash
|
|
git clone https://github.com/monadical-sas/cubbi
|
|
cd cubbi
|
|
uv tool install --with-editable . .
|
|
# You'll have cubbi and cubbix executable files in your PATH, pointing to the local installation.
|
|
```
|
|
|
|
## 📚 Basic Usage
|
|
|
|
```bash
|
|
# Show help message (displays available commands)
|
|
cubbi
|
|
|
|
# Create a new session with the default image (using cubbix alias)
|
|
cubbix
|
|
|
|
# Create a session and run an initial command before the shell starts
|
|
cubbix --run "ls -l"
|
|
|
|
# Create a session, run a command, and exit (no shell prompt)
|
|
cubbix --run "ls -l" --no-shell
|
|
|
|
# List all active sessions
|
|
cubbi session list
|
|
|
|
# Connect to a specific session
|
|
cubbi session connect SESSION_ID
|
|
|
|
# Close a session when done
|
|
cubbi session close SESSION_ID
|
|
|
|
# Close a session quickly (kill instead of graceful stop)
|
|
cubbi session close SESSION_ID --kill
|
|
|
|
# Close all sessions at once
|
|
cubbi session close --all
|
|
|
|
# Close all sessions quickly
|
|
cubbi session close --all --kill
|
|
|
|
# Create a session with a specific image
|
|
cubbix --image goose
|
|
cubbix --image opencode
|
|
cubbix --image crush
|
|
|
|
# Create a session with environment variables
|
|
cubbix -e VAR1=value1 -e VAR2=value2
|
|
|
|
# Mount custom volumes (similar to Docker's -v flag)
|
|
cubbix -v /local/path:/container/path
|
|
cubbix -v ~/data:/data -v ./configs:/etc/app/config
|
|
|
|
# Mount a local directory (current directory or specific path)
|
|
cubbix .
|
|
cubbix /path/to/project
|
|
|
|
# Forward ports from container to host
|
|
cubbix --port 8000 # Forward port 8000
|
|
cubbix --port 8000,3000,5173 # Forward multiple ports (comma-separated)
|
|
cubbix --port 8000 --port 3000 # Forward multiple ports (repeated flag)
|
|
|
|
# Connect to external Docker networks
|
|
cubbix --network teamnet --network dbnet
|
|
|
|
# Restrict network access to specific domains
|
|
cubbix --domains github.com --domains "api.example.com:443"
|
|
|
|
# Connect to MCP servers for extended capabilities
|
|
cubbix --mcp github --mcp jira
|
|
|
|
# Clone a Git repository
|
|
cubbix https://github.com/username/repo
|
|
|
|
# Using the cubbix shortcut (equivalent to cubbi session create)
|
|
cubbix # Creates a session without mounting anything
|
|
cubbix . # Mounts the current directory
|
|
cubbix /path/to/project # Mounts the specified directory
|
|
cubbix https://github.com/username/repo # Clones the repository
|
|
|
|
# Shorthand with MCP servers
|
|
cubbix https://github.com/username/repo --mcp github
|
|
|
|
# Shorthand with an initial command
|
|
cubbix . --run "apt-get update && apt-get install -y my-package"
|
|
|
|
# Execute a command and exit without starting a shell
|
|
cubbix . --run "python script.py" --no-shell
|
|
|
|
# Enable SSH server in the container
|
|
cubbix --ssh
|
|
```
|
|
|
|
## 🖼️ Image Management
|
|
|
|
Cubbi includes an image management system that allows you to build, manage, and use Docker images for different AI tools
|
|
|
|
**Supported Images**
|
|
|
|
| Image Name | Langtrace Support | Single Prompt Command |
|
|
|------------|-------------------|----------------------|
|
|
| goose | yes | `goose run -t 'prompt' --no-session --quiet` |
|
|
| opencode | no | `opencode run -m MODEL 'prompt'` |
|
|
| claudecode | no | `claude -p 'prompt'` |
|
|
| aider | no | `aider --message 'prompt' --yes-always --no-fancy-input` |
|
|
| crush | no | `crush run 'prompt'` |
|
|
|
|
**Automated Testing:**
|
|
|
|
Each image can be tested with single prompt commands using different models:
|
|
|
|
```bash
|
|
# Test a single image with a specific model
|
|
cubbix -i goose -m anthropic/claude-sonnet-4-20250514 --no-connect --no-shell --run "goose run -t 'What is 2+2?' --no-session --quiet"
|
|
|
|
# Test aider with non-interactive flags
|
|
cubbix -i aider -m openai/gpt-4o --no-connect --no-shell --run "aider --message 'What is 2+2?' --yes-always --no-fancy-input --no-check-update"
|
|
|
|
# Test claude-code (note: binary name is 'claude', not 'claude-code')
|
|
cubbix -i claudecode -m anthropic/claude-sonnet-4-20250514 --no-connect --no-shell --run "claude -p 'What is 2+2?'"
|
|
|
|
# Test opencode with model specification
|
|
cubbix -i opencode -m anthropic/claude-sonnet-4-20250514 --no-connect --no-shell --run "opencode run -m anthropic/claude-sonnet-4-20250514 'What is 2+2?'"
|
|
|
|
# Test crush
|
|
cubbix -i crush -m anthropic/claude-sonnet-4-20250514 --no-connect --no-shell --run "crush run 'What is 2+2?'"
|
|
|
|
# Run comprehensive test suite (requires test.sh script)
|
|
./test.sh # Tests all images with multiple models: anthropic/claude-sonnet-4-20250514, openai/gpt-4o, openrouter/openai/gpt-4o, litellm/gpt-oss:120b
|
|
```
|
|
|
|
```bash
|
|
# List available images
|
|
cubbi image list
|
|
|
|
# Get detailed information about an image
|
|
cubbi image info goose
|
|
cubbi image info opencode
|
|
cubbi image info crush
|
|
|
|
# Build an image
|
|
cubbi image build goose
|
|
cubbi image build opencode
|
|
cubbi image build crush
|
|
```
|
|
|
|
Images are defined in the `cubbi/images/` directory, with each subdirectory containing:
|
|
|
|
- `Dockerfile`: Docker image definition
|
|
- `entrypoint.sh`: Container entrypoint script
|
|
- `cubbi-init.sh`: Standardized initialization script
|
|
- `cubbi_image.yaml`: Image metadata and configuration
|
|
- `README.md`: Image documentation
|
|
|
|
Cubbi automatically discovers and loads image definitions from the YAML files.
|
|
```
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Run the tests
|
|
uv run -m pytest
|
|
|
|
# Run linting
|
|
uvx ruff check .
|
|
|
|
# Format code
|
|
uvx ruff format .
|
|
```
|
|
|
|
## ⚙️ Configuration
|
|
|
|
Cubbi supports user-specific configuration via a YAML file located at `~/.config/cubbi/config.yaml`. This allows you to set default values and configure service credentials.
|
|
|
|
### Managing Configuration
|
|
|
|
```bash
|
|
# View all configuration
|
|
cubbi config list
|
|
|
|
# Get a specific configuration value
|
|
cubbi config get langfuse.url
|
|
|
|
# Set configuration values
|
|
cubbi config set langfuse.url "https://cloud.langfuse.com"
|
|
cubbi config set langfuse.public_key "pk-lf-..."
|
|
cubbi config set langfuse.secret_key "sk-lf-..."
|
|
|
|
# Set API keys for various services
|
|
cubbi config set openai.api_key "sk-..."
|
|
cubbi config set anthropic.api_key "sk-ant-..."
|
|
|
|
# Reset configuration to defaults
|
|
cubbi config reset
|
|
```
|
|
|
|
### Default Networks Configuration
|
|
|
|
You can configure default networks that will be applied to every new session:
|
|
|
|
```bash
|
|
# List default networks
|
|
cubbi config network list
|
|
|
|
# Add a network to defaults
|
|
cubbi config network add teamnet
|
|
|
|
# Remove a network from defaults
|
|
cubbi config network remove teamnet
|
|
```
|
|
|
|
### Default Volumes Configuration
|
|
|
|
You can configure default volumes that will be automatically mounted in every new session:
|
|
|
|
```bash
|
|
# List default volumes
|
|
cubbi config volume list
|
|
|
|
# Add a volume to defaults
|
|
cubbi config volume add /local/path:/container/path
|
|
|
|
# Remove a volume from defaults (will prompt if multiple matches found)
|
|
cubbi config volume remove /local/path
|
|
```
|
|
|
|
Default volumes will be combined with any volumes specified using the `-v` flag when creating a session.
|
|
|
|
### Default Ports Configuration
|
|
|
|
You can configure default ports that will be automatically forwarded in every new session:
|
|
|
|
```bash
|
|
# List default ports
|
|
cubbi config port list
|
|
|
|
# Add a single port to defaults
|
|
cubbi config port add 8000
|
|
|
|
# Add multiple ports to defaults (comma-separated)
|
|
cubbi config port add 8000,3000,5173
|
|
|
|
# Remove a port from defaults
|
|
cubbi config port remove 8000
|
|
```
|
|
|
|
Default ports will be combined with any ports specified using the `--port` flag when creating a session.
|
|
|
|
### Default MCP Servers Configuration
|
|
|
|
You can configure default MCP servers that sessions will automatically connect to:
|
|
|
|
```bash
|
|
# List default MCP servers
|
|
cubbi config mcp list
|
|
|
|
# Add an MCP server to defaults
|
|
cubbi config mcp add github
|
|
|
|
# Remove an MCP server from defaults
|
|
cubbi config mcp remove github
|
|
```
|
|
|
|
When adding new MCP servers, they are added to defaults by default. Use the `--no-default` flag to prevent this:
|
|
|
|
```bash
|
|
cubbi mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=xxxx github mcp/github --no-default
|
|
```
|
|
|
|
When creating sessions, if no MCP server is specified with `--mcp`, the default MCP servers will be used automatically.
|
|
|
|
### External Network Connectivity
|
|
|
|
Cubbi containers can connect to external Docker networks, allowing them to communicate with other services in those networks:
|
|
|
|
```bash
|
|
# Create a session connected to external networks
|
|
cubbi session create --network teamnet --network dbnet
|
|
```
|
|
|
|
**Important**: Networks must be "attachable" to be joined by Cubbi containers. Here's how to create attachable networks:
|
|
|
|
```bash
|
|
# Create an attachable network with Docker
|
|
docker network create --driver bridge --attachable teamnet
|
|
|
|
# Example docker-compose.yml with attachable network
|
|
# docker-compose.yml
|
|
version: '3'
|
|
services:
|
|
web:
|
|
image: nginx
|
|
networks:
|
|
- teamnet
|
|
|
|
networks:
|
|
teamnet:
|
|
driver: bridge
|
|
attachable: true # This is required for Cubbi containers to connect
|
|
```
|
|
|
|
### Service Credentials
|
|
|
|
Service credentials like API keys configured in `~/.config/cubbi/config.yaml` are automatically passed to containers as environment variables:
|
|
|
|
| Config Setting | Environment Variable |
|
|
|----------------|---------------------|
|
|
| `langfuse.url` | `LANGFUSE_URL` |
|
|
| `langfuse.public_key` | `LANGFUSE_INIT_PROJECT_PUBLIC_KEY` |
|
|
| `langfuse.secret_key` | `LANGFUSE_INIT_PROJECT_SECRET_KEY` |
|
|
| `openai.api_key` | `OPENAI_API_KEY` |
|
|
| `anthropic.api_key` | `ANTHROPIC_API_KEY` |
|
|
| `openrouter.api_key` | `OPENROUTER_API_KEY` |
|
|
| `google.api_key` | `GOOGLE_API_KEY` |
|
|
|
|
## 🌐 MCP Server Management
|
|
|
|
MCP (Model Control Protocol) servers provide tool-calling capabilities to AI models, enhancing their ability to interact with external services, databases, and systems. Cubbi supports multiple types of MCP servers:
|
|
|
|
1. **Remote HTTP SSE servers** - External MCP servers accessed over HTTP
|
|
2. **Docker-based MCP servers** - Local MCP servers running in Docker containers, with a SSE proxy for stdio-to-SSE conversion
|
|
|
|
### Managing MCP Servers
|
|
|
|
```bash
|
|
# List all configured MCP servers and their status
|
|
cubbi mcp list
|
|
|
|
# View detailed status of an MCP server
|
|
cubbi mcp status github
|
|
|
|
# Start/stop/restart individual MCP servers
|
|
cubbi mcp start github
|
|
cubbi mcp stop github
|
|
cubbi mcp restart github
|
|
|
|
# Start all MCP servers at once
|
|
cubbi mcp start --all
|
|
|
|
# Stop and remove all MCP servers at once
|
|
cubbi mcp stop --all
|
|
|
|
# Run the MCP Inspector to visualize and interact with MCP servers
|
|
# It automatically joins all MCP networks for seamless DNS resolution
|
|
# Uses two ports: frontend UI (default: 5173) and backend API (default: 3000)
|
|
cubbi mcp inspector
|
|
|
|
# Run the MCP Inspector with custom ports
|
|
cubbi mcp inspector --client-port 6173 --server-port 6174
|
|
|
|
# Run the MCP Inspector in detached mode
|
|
cubbi mcp inspector --detach
|
|
|
|
# Stop the MCP Inspector
|
|
cubbi mcp inspector --stop
|
|
|
|
# View MCP server logs
|
|
cubbi mcp logs github
|
|
|
|
# Remove an MCP server configuration
|
|
cubbi mcp remove github
|
|
```
|
|
|
|
### Adding MCP Servers
|
|
|
|
Cubbi supports different types of MCP servers:
|
|
|
|
```bash
|
|
# Example of docker-based MCP server
|
|
cubbi mcp add fetch mcp/fetch
|
|
cubbi mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=xxxx github mcp/github
|
|
|
|
# Example of SSE-based MCP server
|
|
cubbi mcp add myserver https://myssemcp.com
|
|
```
|
|
|
|
### Using MCP Servers with Sessions
|
|
|
|
MCP servers can be attached to sessions when they are created:
|
|
|
|
```bash
|
|
# Create a session with a single MCP server
|
|
cubbi session create --mcp github
|
|
|
|
# Create a session with multiple MCP servers
|
|
cubbi session create --mcp github --mcp jira
|
|
```
|
|
|
|
MCP servers are persistent and can be shared between sessions. They continue running even when sessions are closed, allowing for efficient reuse across multiple sessions.
|
|
|
|
## 📜 License
|
|
|
|
Cubbi is licensed under the [MIT License](LICENSE).
|