selfhostyourtech/cubbi
2
0
Fork 0
mirror of https://github.com/Monadical-SAS/cubbi.git synced 2025-12-20 12:19:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix(cli): rename MAI->MC

Browse Source
This commit is contained in:
Mathieu Virbel
2025-03-11 10:41:27 -06:00
parent 74c723db7b
commit 354834fff7
4 changed files with 87 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files

169
SPECIFICATIONS.md
View File

@@ -1,19 +1,22 @@
# MAI - Monadical AI Container Tool # MC - Monadical AI Container Tool
## Overview ## Overview
MAI (Monadical AI Container) is a command-line tool for managing ephemeral containers that run AI tools and development environments. It works with both local Docker and a dedicated remote web service that manages containers in a Docker-in-Docker (DinD) environment. MC (Monadical Container) is a command-line tool for managing ephemeral
containers that run AI tools and development environments. It works with both
local Docker and a dedicated remote web service that manages containers in a
Docker-in-Docker (DinD) environment.
## Technology Stack ## Technology Stack
### MAI Service ### MC Service
- **Web Framework**: FastAPI for high-performance, async API endpoints - **Web Framework**: FastAPI for high-performance, async API endpoints
- **Package Management**: uv (Astral) for dependency management - **Package Management**: uv (Astral) for dependency management
- **Database**: SQLite for development, PostgreSQL for production - **Database**: SQLite for development, PostgreSQL for production
- **Container Management**: Docker SDK for Python - **Container Management**: Docker SDK for Python
- **Authentication**: OAuth 2.0 integration with Authentik - **Authentication**: OAuth 2.0 integration with Authentik
### MAI CLI ### MC CLI
- **Language**: Python - **Language**: Python
- **Package Management**: uv for dependency management - **Package Management**: uv for dependency management
- **Distribution**: Standalone binary via PyInstaller or similar - **Distribution**: Standalone binary via PyInstaller or similar
@@ -23,8 +26,8 @@ MAI (Monadical AI Container) is a command-line tool for managing ephemeral conta
### Components ### Components
1. **CLI Tool (`mai`)**: The command-line interface users interact with 1. **CLI Tool (`mc`)**: The command-line interface users interact with
2. **MAI Service**: A web service that handles remote container execution 2. **MC Service**: A web service that handles remote container execution
3. **Container Drivers**: Predefined container templates for various AI tools 3. **Container Drivers**: Predefined container templates for various AI tools
### Architecture Diagram ### Architecture Diagram
@@ -32,8 +35,8 @@ MAI (Monadical AI Container) is a command-line tool for managing ephemeral conta
``` ```
┌─────────────┐ ┌─────────────────────────┐ ┌─────────────┐ ┌─────────────────────────┐
│ │ │ │ │ │ │ │
│ MAI CLI │◄─────────►│ Local Docker Daemon │ │ MC CLI │◄─────────►│ Local Docker Daemon │
│ (mai) │ │ │ │ (mc) │ │ │
│ │ └─────────────────────────┘ │ │ └─────────────────────────┘
└──────┬──────┘ └──────┬──────┘
│ │
@@ -41,7 +44,7 @@ MAI (Monadical AI Container) is a command-line tool for managing ephemeral conta
│ │
┌──────▼──────┐ ┌─────────────────────────┐ ┌──────▼──────┐ ┌─────────────────────────┐
│ │ │ │ │ │ │ │
│ MAI Service │◄─────────►│ Docker-in-Docker │ │ MC Service │◄─────────►│ Docker-in-Docker │
│ (Web API) │ │ │ │ (Web API) │ │ │
│ │ └─────────────────────────┘ │ │ └─────────────────────────┘
└─────────────┘ └─────────────┘
@@ -60,7 +63,7 @@ MAI (Monadical AI Container) is a command-line tool for managing ephemeral conta
- **Session**: An active container instance with a specific driver - **Session**: An active container instance with a specific driver
- **Driver**: A predefined container template with specific AI tools installed - **Driver**: A predefined container template with specific AI tools installed
- **Remote**: A configured MAI service instance - **Remote**: A configured MC service instance
## CLI Tool Commands ## CLI Tool Commands
@@ -68,80 +71,80 @@ MAI (Monadical AI Container) is a command-line tool for managing ephemeral conta
```bash ```bash
# Create a new session locally (shorthand) # Create a new session locally (shorthand)
mai mc
# List active sessions on local system # List active sessions on local system
mai session list mc session list
# Create a new session locally # Create a new session locally
mai session create [OPTIONS] mc session create [OPTIONS]
# Create a session with a specific driver # Create a session with a specific driver
mai session create --driver goose mc session create --driver goose
# Create a session with a specific project repository # Create a session with a specific project repository
mai session create --driver goose --project github.com/hello/private mc session create --driver goose --project github.com/hello/private
# Create a session with a project (shorthand) # Create a session with a project (shorthand)
mai git@github.com:hello/private mc git@github.com:hello/private
# Close a specific session # Close a specific session
mai session close <id> mc session close <id>
# Connect to an existing session # Connect to an existing session
mai session connect <id> mc session connect <id>
# Stop the current session (from inside the container) # Stop the current session (from inside the container)
mai stop mc stop
``` ```
### Remote Management ### Remote Management
```bash ```bash
# Add a remote MAI service # Add a remote MC service
mai remote add <name> <url> mc remote add <name> <url>
# List configured remote services # List configured remote services
mai remote list mc remote list
# Remove a remote service # Remove a remote service
mai remote remove <name> mc remote remove <name>
# Authenticate with a remote service # Authenticate with a remote service
mai -r <remote_name> auth mc -r <remote_name> auth
# Create a session on a remote service # Create a session on a remote service
mai -r <remote_name> [session create] mc -r <remote_name> [session create]
# List sessions on a remote service # List sessions on a remote service
mai -r <remote_name> session list mc -r <remote_name> session list
``` ```
### Environment Variables ### Environment Variables
```bash ```bash
# Set environment variables for a session # Set environment variables for a session
mai session create -e VAR1=value1 -e VAR2=value2 mc session create -e VAR1=value1 -e VAR2=value2
# Set environment variables for a remote session # Set environment variables for a remote session
mai -r <remote_name> session create -e VAR1=value1 mc -r <remote_name> session create -e VAR1=value1
``` ```
### Logging ### Logging
```bash ```bash
# Stream logs from a session # Stream logs from a session
mai session logs <id> mc session logs <id>
# Stream logs with follow option # Stream logs with follow option
mai session logs <id> -f mc session logs <id> -f
``` ```
## MAI Service Specification ## MC Service Specification
### Overview ### Overview
The MAI Service is a web service that manages ephemeral containers in a Docker-in-Docker environment. It provides a REST API for container lifecycle management, authentication, and real-time log streaming. The MC Service is a web service that manages ephemeral containers in a Docker-in-Docker environment. It provides a REST API for container lifecycle management, authentication, and real-time log streaming.
### API Endpoints ### API Endpoints
@@ -156,19 +159,19 @@ POST /auth/logout - Invalidate current token
### Authentik Integration ### Authentik Integration
The MAI Service integrates with Authentik at https://authentik.monadical.io using OAuth 2.0: The MC Service integrates with Authentik at https://authentik.monadical.io using OAuth 2.0:
1. **Application Registration**: 1. **Application Registration**:
- MAI Service is registered as an OAuth application in Authentik - MC Service is registered as an OAuth application in Authentik
- Configured with redirect URI to `/auth/callback` - Configured with redirect URI to `/auth/callback`
- Assigned appropriate scopes for user identification - Assigned appropriate scopes for user identification
2. **Authentication Flow**: 2. **Authentication Flow**:
- User initiates authentication via CLI - User initiates authentication via CLI
- MAI CLI opens browser to Authentik authorization URL - MC CLI opens browser to Authentik authorization URL
- User logs in through Authentik's interface - User logs in through Authentik's interface
- Authentik redirects to callback URL with authorization code - Authentik redirects to callback URL with authorization code
- MAI Service exchanges code for access and refresh tokens - MC Service exchanges code for access and refresh tokens
- CLI receives and securely stores tokens - CLI receives and securely stores tokens
3. **Token Management**: 3. **Token Management**:
@@ -207,19 +210,19 @@ DELETE /projects/{id} - Remove a project
### Service Configuration ### Service Configuration
```yaml ```yaml
# mai-service.yaml # mc-service.yaml
server: server:
port: 3000 port: 3000
host: 0.0.0.0 host: 0.0.0.0
docker: docker:
socket: /var/run/docker.sock socket: /var/run/docker.sock
network: mai-network network: mc-network
auth: auth:
provider: authentik provider: authentik
url: https://authentik.monadical.io url: https://authentik.monadical.io
clientId: mai-service clientId: mc-service
logging: logging:
providers: providers:
@@ -231,13 +234,13 @@ logging:
drivers: drivers:
- name: goose - name: goose
image: monadical/mai-goose:latest image: monadical/mc-goose:latest
env: env:
MCP_HOST: http://mcp:8000 MCP_HOST: http://mcp:8000
- name: aider - name: aider
image: monadical/mai-aider:latest image: monadical/mc-aider:latest
- name: claude-code - name: claude-code
image: monadical/mai-claude-code:latest image: monadical/mc-claude-code:latest
projects: projects:
storage: storage:
@@ -251,7 +254,7 @@ projects:
### Docker-in-Docker Implementation ### Docker-in-Docker Implementation
The MAI Service runs in a container with access to the host's Docker socket, allowing it to create and manage sibling containers. This approach provides: The MC Service runs in a container with access to the host's Docker socket, allowing it to create and manage sibling containers. This approach provides:
1. Isolation between containers 1. Isolation between containers
2. Simple lifecycle management 2. Simple lifecycle management
@@ -266,7 +269,7 @@ For remote connections to containers, the service provides two methods:
### Logging Implementation ### Logging Implementation
The MAI Service implements log collection and forwarding: The MC Service implements log collection and forwarding:
1. Container logs are captured using Docker's logging drivers 1. Container logs are captured using Docker's logging drivers
2. Logs are forwarded to configured providers (Fluentd, Langfuse) 2. Logs are forwarded to configured providers (Fluentd, Langfuse)
@@ -280,21 +283,21 @@ Users can add projects with associated credentials:
```bash ```bash
# Add a project with SSH key # Add a project with SSH key
mai project add github.com/hello/private --ssh-key ~/.ssh/id_ed25519 mc project add github.com/hello/private --ssh-key ~/.ssh/id_ed25519
# Add a project with token authentication # Add a project with token authentication
mai project add github.com/hello/private --token ghp_123456789 mc project add github.com/hello/private --token ghp_123456789
# List all projects # List all projects
mai project list mc project list
# Remove a project # Remove a project
mai project remove github.com/hello/private mc project remove github.com/hello/private
``` ```
### Project Configuration ### Project Configuration
Projects are stored in the MAI service and referenced by their repository URL. The configuration includes: Projects are stored in the MC service and referenced by their repository URL. The configuration includes:
```yaml ```yaml
# Project configuration # Project configuration
@@ -319,51 +322,51 @@ Each driver is a Docker image with a standardized structure:
``` ```
/ /
├── entrypoint.sh # Container initialization ├── entrypoint.sh # Container initialization
├── mai-init.sh # Standardized initialization script ├── mc-init.sh # Standardized initialization script
├── mai-driver.yaml # Driver metadata and configuration ├── mc-driver.yaml # Driver metadata and configuration
├── tool/ # AI tool installation ├── tool/ # AI tool installation
└── ssh/ # SSH server configuration └── ssh/ # SSH server configuration
``` ```
### Standardized Initialization Script ### Standardized Initialization Script
All drivers include a standardized `mai-init.sh` script that handles common initialization tasks: All drivers include a standardized `mc-init.sh` script that handles common initialization tasks:
```bash ```bash
#!/bin/bash #!/bin/bash
# Project initialization # Project initialization
if [ -n "$MAI_PROJECT_URL" ]; then if [ -n "$MC_PROJECT_URL" ]; then
echo "Initializing project: $MAI_PROJECT_URL" echo "Initializing project: $MC_PROJECT_URL"
# Set up SSH key if provided # Set up SSH key if provided
if [ -n "$MAI_GIT_SSH_KEY" ]; then if [ -n "$MC_GIT_SSH_KEY" ]; then
mkdir -p ~/.ssh mkdir -p ~/.ssh
echo "$MAI_GIT_SSH_KEY" > ~/.ssh/id_ed25519 echo "$MC_GIT_SSH_KEY" > ~/.ssh/id_ed25519
chmod 600 ~/.ssh/id_ed25519 chmod 600 ~/.ssh/id_ed25519
ssh-keyscan github.com >> ~/.ssh/known_hosts 2>/dev/null ssh-keyscan github.com >> ~/.ssh/known_hosts 2>/dev/null
fi fi
# Set up token if provided # Set up token if provided
if [ -n "$MAI_GIT_TOKEN" ]; then if [ -n "$MC_GIT_TOKEN" ]; then
git config --global credential.helper store git config --global credential.helper store
echo "https://$MAI_GIT_TOKEN:x-oauth-basic@github.com" > ~/.git-credentials echo "https://$MC_GIT_TOKEN:x-oauth-basic@github.com" > ~/.git-credentials
fi fi
# Clone repository # Clone repository
git clone $MAI_PROJECT_URL /app git clone $MC_PROJECT_URL /app
cd /app cd /app
# Run project-specific initialization if present # Run project-specific initialization if present
if [ -f "/app/.mai/init.sh" ]; then if [ -f "/app/.mc/init.sh" ]; then
bash /app/.mai/init.sh bash /app/.mc/init.sh
fi fi
fi fi
# Driver-specific initialization continues... # Driver-specific initialization continues...
``` ```
### Driver Configuration (mai-driver.yaml) ### Driver Configuration (mc-driver.yaml)
```yaml ```yaml
name: goose name: goose
@@ -372,7 +375,7 @@ version: 1.0.0
maintainer: team@monadical.com maintainer: team@monadical.com
init: init:
pre_command: /mai-init.sh pre_command: /mc-init.sh
command: /entrypoint.sh command: /entrypoint.sh
environment: environment:
@@ -386,21 +389,21 @@ environment:
required: false required: false
# Project environment variables # Project environment variables
- name: MAI_PROJECT_URL - name: MC_PROJECT_URL
description: Project repository URL description: Project repository URL
required: false required: false
- name: MAI_PROJECT_TYPE - name: MC_PROJECT_TYPE
description: Project repository type (git, svn, etc.) description: Project repository type (git, svn, etc.)
required: false required: false
default: git default: git
- name: MAI_GIT_SSH_KEY - name: MC_GIT_SSH_KEY
description: SSH key for Git authentication description: SSH key for Git authentication
required: false required: false
sensitive: true sensitive: true
- name: MAI_GIT_TOKEN - name: MC_GIT_TOKEN
description: Token for Git authentication description: Token for Git authentication
required: false required: false
sensitive: true sensitive: true
@@ -431,15 +434,15 @@ volumes:
## Deployment ## Deployment
### MAI Service Deployment ### MC Service Deployment
```yaml ```yaml
# docker-compose.yml for MAI Service # docker-compose.yml for MC Service
version: '3.8' version: '3.8'
services: services:
mai-service: mc-service:
image: monadical/mai-service:latest image: monadical/mc-service:latest
volumes: volumes:
- /var/run/docker.sock:/var/run/docker.sock - /var/run/docker.sock:/var/run/docker.sock
- ./config:/app/config - ./config:/app/config
@@ -449,10 +452,10 @@ services:
- AUTH_URL=https://authentik.monadical.io - AUTH_URL=https://authentik.monadical.io
- LANGFUSE_API_KEY=your_api_key - LANGFUSE_API_KEY=your_api_key
networks: networks:
- mai-network - mc-network
networks: networks:
mai-network: mc-network:
driver: bridge driver: bridge
``` ```
@@ -462,33 +465,33 @@ networks:
1. User adds project repository with authentication: 1. User adds project repository with authentication:
```bash ```bash
mai project add github.com/hello/private --ssh-key ~/.ssh/id_ed25519 mc project add github.com/hello/private --ssh-key ~/.ssh/id_ed25519
``` ```
2. MAI CLI reads the SSH key, encrypts it, and sends to MAI Service 2. MC CLI reads the SSH key, encrypts it, and sends to MC Service
3. MAI Service stores the project configuration securely 3. MC Service stores the project configuration securely
### Using a Project in a Session ### Using a Project in a Session
1. User creates a session with a project: 1. User creates a session with a project:
```bash ```bash
mai -r monadical git@github.com:hello/private mc -r monadical git@github.com:hello/private
``` ```
2. MAI Service: 2. MC Service:
- Identifies the project from the URL - Identifies the project from the URL
- Retrieves project authentication details - Retrieves project authentication details
- Sets up environment variables: - Sets up environment variables:
``` ```
MAI_PROJECT_URL=git@github.com:hello/private MC_PROJECT_URL=git@github.com:hello/private
MAI_PROJECT_TYPE=git MC_PROJECT_TYPE=git
MAI_GIT_SSH_KEY=<contents of the SSH key> MC_GIT_SSH_KEY=<contents of the SSH key>
``` ```
- Creates container with these environment variables - Creates container with these environment variables
3. Container initialization: 3. Container initialization:
- The standardized `mai-init.sh` script detects the project environment variables - The standardized `mc-init.sh` script detects the project environment variables
- Sets up SSH key or token authentication - Sets up SSH key or token authentication
- Clones the repository to `/app` - Clones the repository to `/app`
- Runs any project-specific initialization scripts - Runs any project-specific initialization scripts
@@ -498,7 +501,7 @@ networks:
## Implementation Roadmap ## Implementation Roadmap
1. **Phase 1**: Local CLI tool with Docker integration 1. **Phase 1**: Local CLI tool with Docker integration
2. **Phase 2**: MAI Service REST API with basic container management 2. **Phase 2**: MC Service REST API with basic container management
3. **Phase 3**: Authentication and secure connections 3. **Phase 3**: Authentication and secure connections
4. **Phase 4**: Project management functionality 4. **Phase 4**: Project management functionality
5. **Phase 5**: Driver implementation (Goose, Aider, Claude Code) 5. **Phase 5**: Driver implementation (Goose, Aider, Claude Code)

1
mcontainer/drivers/__init__.py
View File

@@ -1 +0,0 @@
"""Driver definitions for MAI"""

1
mcontainer/utils/__init__.py
View File

@@ -1 +0,0 @@
"""Utility functions for MAI"""

2
mcontainer/utils/git.py
View File

@@ -1,5 +1,5 @@
""" """
Git repository handling utilities for MAI Git repository handling utilities for MC
""" """
import re import re