gitarsenal-cli/README.md

CLI tool for creating Modal sandboxes with GitHub repositories

# GitArsenal CLI

**Run any GitHub repository instantly with pre-configured GPU environments.**

GitArsenal CLI makes it incredibly easy to run any GitHub repository without worrying about setup, dependencies, or environment configuration. Just point it at a repository and start coding with GPU acceleration.

## Why GitArsenal CLI?

- **Zero Setup**: No need to install dependencies, configure environments, or manage GPU drivers
- **GPU Ready**: Every environment comes with GPU acceleration (A10G, A100, H100)
- **Persistent Storage**: Your work and data persist between sessions
- **SSH Access**: Connect directly to your running environment
- **API Key Management**: Securely store and auto-inject API keys for services like OpenAI, Weights & Biases, and Hugging Face

## Quick Start

### Run any GitHub repository

```bash
# Basic usage - clone and run any repo
gitarsenal --repo https://github.com/username/awesome-project.git

# With GPU acceleration
gitarsenal --gpu A10G --repo https://github.com/username/awesome-project.git

# With custom setup commands
gitarsenal --gpu A100 --repo https://github.com/username/awesome-project.git --setup-commands "pip install -r requirements.txt" "python setup.py install"

# Using E2B sandbox provider (faster startup, no GPU)
gitarsenal --sandbox-provider e2b --repo https://github.com/username/awesome-project.git
```

### Examples

```bash
# Run a machine learning project
gitarsenal --gpu A100 --repo https://github.com/username/transformer-project.git --setup-commands "pip install torch transformers" "wandb login"

# Run a web development project
gitarsenal --repo https://github.com/username/react-app.git --setup-commands "npm install" "npm start"

# Run a data science project with persistent storage
gitarsenal --gpu A10G --repo https://github.com/username/data-analysis.git --volume-name my-data --setup-commands "pip install pandas numpy matplotlib"
```

## API Key Management

Store your API keys once and use them across all projects:

```bash
# Add API keys for seamless integration
gitarsenal keys add --service openai
gitarsenal keys add --service wandb
gitarsenal keys add --service huggingface

# View your saved keys
gitarsenal keys list

# Remove a key
gitarsenal keys delete --service openai
```

### Supported Services

- **OpenAI** - For debugging and AI assistance
- **Weights & Biases** - For experiment tracking
- **Hugging Face** - For model access and downloads

## Features

### Sandbox Providers

GitArsenal supports multiple sandbox providers to fit your needs:

#### Modal Sandbox (Default)
- Full GPU support (A10G, A100, H100, etc.)
- Persistent storage with volumes
- SSH access
- Longer startup time

```bash
# Explicitly use Modal sandbox
gitarsenal --sandbox-provider modal --repo https://github.com/username/project.git
```

#### E2B Sandbox
- Faster startup time
- Lightweight environment
- No GPU support
- Ideal for quick testing and development

```bash
# Use E2B sandbox for faster startup
gitarsenal --sandbox-provider e2b --repo https://github.com/username/project.git
```

### Automatic Environment Setup
The CLI automatically:
- Clones your repository
- Installs dependencies based on your setup commands
- Configures GPU acceleration
- Sets up persistent storage
- Injects your saved API keys

### Persistent Storage
Keep your work safe with persistent volumes:

```bash
# Create a persistent environment
gitarsenal --repo https://github.com/username/project.git --volume-name my-work

# Your data, models, and work will persist between sessions
```

### SSH Access
Connect directly to your running environment:

```bash
# Get SSH connection details
gitarsenal --repo https://github.com/username/project.git --ssh

# Connect via SSH to your environment
ssh user@your-environment-ip
```

## Workflow

1. **Choose a repository** - Any GitHub repo you want to work with
2. **Run the command** - Specify GPU, setup commands, and storage
3. **Start coding** - Your environment is ready with all dependencies installed
4. **Save your work** - Use persistent volumes to keep your progress

## Perfect For

- **Machine Learning Projects** - GPU-accelerated training with pre-configured environments
- **Data Science** - Jupyter notebooks with all dependencies ready
- **Web Development** - Full-stack projects with development servers
- **Research** - Reproducible environments for academic work
- **Hackathons** - Quick setup for rapid prototyping

## Getting Started

1. Install the CLI (see installation instructions)
2. Add your API keys: `gitarsenal keys add --service openai`
3. Run any repository: `gitarsenal --repo https://github.com/username/project.git`
4. Start coding!

No more "works on my machine" - every environment is identical and ready to go.