🚀 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
• uv

📥 Installation

# Via uv
uv tool install cubbi

# Without installation
# (meaning all commands below must be prefixed with `uvx`)
uvx cubbi

Then compile your first image:

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:

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

# 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

... [View full README on GitHub](https://github.com/Monadical-SAS/cubbi#readme)