Metadata-Version: 2.4
Name: modal-uv
Version: 0.2.0
Summary: Run uv commands on Modal.com with GPU and direct file sync
Requires-Python: >=3.12
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: modal>=1.4.3
Requires-Dist: pathspec>=0.12.1
Requires-Dist: pydantic-settings[yaml]>=2.7.0
Requires-Dist: typer>=0.15.0
Requires-Dist: uvicorn>=0.34.0
Description-Content-Type: text/markdown

# modal-uv

Run `uv` commands on Modal.com with GPU support, direct file sync, async execution IDs, logs, abort, and persistent Modal volumes.

## Installation

### Option 1: Coding Agent (Recommended)

Paste this prompt to your coding agent (opencode, Claude Code, Gemini CLI, etc.):

```
Install modal-uv globally and set it up:
1. Run: pip install modal-uv
2. Run: modal-uv onboard
   - This opens a browser for Modal OAuth authentication
   - Complete the auth flow in the browser
   - It also installs the use-modal-uv skill to detected coding agents
3. In the project repo, run: modal-uv init
   - This creates modal-uv.yaml with defaults if missing
   - It creates .modal-uv/ for generated state and adds it to .gitignore
4. Edit modal-uv.yaml to set app_name, gpu, and volume.name for this project
5. Run: modal-uv doctor
   - This checks modal-uv health: auth state, volume existence, app deployment, daemon status
   - Does not wake the container
```

### Option 2: Manual Getting Started

```bash
pip install modal-uv
```

Authenticate with Modal (opens browser for OAuth):

```bash
modal-uv onboard
```

This also installs the `use-modal-uv` skill to detected coding agents (`~/.config/opencode/`, `~/.claude/`, `~/.agents/`).

In your project repo, initialize modal-uv files:

```bash
modal-uv init
```

This creates `modal-uv.yaml` with defaults (using the directory name as `app_name`) if missing, and creates `.modal-uv/` for generated state with a `.gitignore` entry.

Edit `modal-uv.yaml` to configure your app:

```yaml
app_name: "my-project"
gpu: "T4"
work_dir: "/tmp/work"

volumes:
  - name: "modal-uv-cache"
    mount_path: "/mnt/volume"
    commit_interval_seconds: 30

env: {}

runtime:
  scaledown_window_seconds: 300

image:
  python_version: "3.12"
  base_image: "python:3.12-slim"

sync:
  ignore:
    - "data/**"
    - "*.ckpt"
```

Then run commands on Modal:

```bash
modal-uv run -- pytest
```

## Repository Configuration

`modal-uv.yaml` at the repository root is discovered by walking up from the current directory, similar to `git` or `uv`.

Fields:

- `app_name`: Modal app name (required)
- `gpu`: GPU type, such as `T4`, `A10G`, `A100`, `H100`, or `L4`
- `work_dir`: Working directory inside the Modal container (default: `/root/work`)
- `volumes`: Modal volumes to mount in the container; may be empty or omitted
- `volumes[].name`: Modal volume name
- `volumes[].mount_path`: Mount path in the container (default: `/root/.cache`)
- `volumes[].commit_interval_seconds`: Periodic Modal Volume commit interval while a command runs (default: `30`)
- `env`: Extra container environment variables merged over modal-uv defaults
- `runtime.scaledown_window_seconds`: Modal worker scaledown window (default: `300`)
- `runtime.exec`: Optional shell executable for `modal-uv exec`; if omitted, the remote Worker uses `$SHELL`, then `/bin/sh`
- `image.python_version`: Python version (default: `3.12`)
- `image.base_image`: Base Docker image (default: `python:3.12-slim`)
- `sync.ignore`: gitignore-style patterns excluded from direct sync

## Repo-Local State

`modal-uv` creates `.modal-uv/` at the repo root for generated/runtime files and ensures the root `.gitignore` ignores it.

Examples of generated files:

- `.modal-uv/deployment.py`
- `.modal-uv/daemon.pid`
- `.modal-uv/daemon.sock`
- `.modal-uv/daemon.log`

`.modal-uv/` is not normally synced to the Modal work directory.

## Sync And Deployment

`modal-uv run` and `modal-uv exec` scan local files, apply built-in ignores plus `sync.ignore`, ask the warm Modal container which files are missing or stale, upload only those files, spawn the execution, print the Modal function call ID, and return immediately.

The detached daemon lazily ensures the Modal app is deployed before running work. It generates `.modal-uv/deployment.py` and redeploys when the deployment fingerprint changes. The fingerprint includes the deployment template, Modal-relevant config values, and the repo `pyproject.toml` SHA256 when present.

During a running command, `modal-uv` periodically commits the Modal Volume every `volume.commit_interval_seconds` seconds, plus one final commit after the command exits. This persists outputs and checkpoints written under the mounted volume during long runs.

Ordinary source changes do not redeploy the app; they are handled by direct sync.

Modal authentication remains Modal's normal user-global authentication. `modal-uv` does not create repo-local auth files.

## Commands

Run `uv` commands on Modal:

```bash
modal-uv run -- pytest
modal-uv run -- python -m lab
modal-uv run -- python train.py --epochs 10
```

Tail or abort a spawned execution:

```bash
modal-uv logs fc-...
modal-uv abort fc-...
```

Run shell-style commands in the synced Modal work directory:

```bash
modal-uv exec -- nvidia-smi
modal-uv exec -- 'ls -la && pwd'
```

Open Modal's native interactive shell through the passthrough command:

```bash
modal-uv modal -- shell
```

Show Modal app status:

```bash
modal-uv status
```

Check the configured Modal volume directly:

```bash
modal-uv modal -- volume ls modal-uv-cache
```

Initialize or align modal-uv files in the current directory:

```bash
modal-uv init
```

Run any Modal CLI command through the modal-uv environment:

```bash
modal-uv modal -- app list
modal-uv modal -- volume ls
```

Daemon helpers:

```bash
modal-uv daemon-status
modal-uv daemon-stop
```

## Updates

Upgrade modal-uv and refresh the skill on all detected agents:

```bash
modal-uv update
```

Install the skill to a specific agent (`opencode`, `claude`, `agents`) or an explicit directory path:

```bash
modal-uv install-skill opencode
modal-uv install-skill /path/to/skills/dir
```

Detected agents are based on which config directories exist (`~/.config/opencode/`, `~/.claude/`, `~/.agents/`).

Use `--config` or `-c` to specify a custom config file:

```bash
modal-uv run --config path/to/modal-uv.yaml -- pytest
```

## Checks

```bash
uv run ruff check .
uv run ruff format --check .
uv run pytest
```
