---
description: Deploy your app to the badge via USB Mass Storage Mode
---

# Deploy to Badge

Guide the user through deploying their MonaOS app to the badge using USB Mass Storage Mode.

## Critical Information

⚠️ **IMPORTANT**: The `/system/apps/` directory is **READ-ONLY** via mpremote. You MUST use USB Mass Storage Mode to install apps.

## Steps to Deploy

### 1. Verify App Structure

First, check that the app directory exists and contains required files:
- `__init__.py` (required)
- `icon.png` (required, 24x24 pixels)
- `assets/` (optional)

If files are missing, inform the user what's needed.

### 2. Enter USB Mass Storage Mode

Instruct the user:

1. **Connect badge** via USB-C cable
2. **Press RESET button TWICE quickly** (double-click the button on the back of the badge)
3. **Wait 2-3 seconds** - Badge will appear as **"BADGER"** drive
4. **Verify**: The drive should appear in Finder (macOS), File Explorer (Windows), or file manager (Linux)

### 3. Copy App to Badge

Provide OS-specific instructions:

**macOS/Linux:**
```bash
cp -r {app_name} /Volumes/BADGER/apps/
```

**Windows (PowerShell):**
```powershell
xcopy {app_name} D:\apps\{app_name}\ /E /I
```
(Replace `D:` with actual BADGER drive letter)

**Or manually:**
1. Open BADGER drive in file manager
2. Navigate to `apps/` folder
3. Drag `{app_name}` folder into `apps/`

### 4. Exit Mass Storage Mode

**macOS:**
```bash
diskutil eject /Volumes/BADGER
```
Or right-click BADGER in Finder → Eject

**Windows:**
- Right-click BADGER drive → "Eject"
- Or use "Safely Remove Hardware" in system tray

**Linux:**
```bash
sudo umount /media/$USER/BADGER
```

### 5. Reboot Badge

**Press RESET button once** on the badge. It will reboot into MonaOS with your new app installed!

### 6. Launch Your App

1. Navigate the MonaOS menu using UP/DOWN and A/C buttons
2. Find your app (look for the icon you created)
3. Press B to launch

## Troubleshooting

### App doesn't appear in menu
- Check that you copied the entire folder, not just the files inside
- Verify the folder is in `/Volumes/BADGER/apps/` (or `D:\apps\` on Windows)
- Make sure `__init__.py` and `icon.png` are both present
- If you have 7+ apps, you may need to install the paginated menu (see below)

### Badge shows only 6 apps
The default MonaOS menu shows only 6 apps. To enable pagination:

1. Enter Mass Storage Mode again (double-press RESET)
2. Download paginated menu: https://raw.githubusercontent.com/badger/home/refs/heads/main/badge/apps/menu/__init__.py
3. Backup original: Copy `/Volumes/BADGER/apps/menu/__init__.py` to `__init__-backup.py`
4. Replace with paginated version
5. Eject and reboot

### "Read-only file system" error with mpremote
This confirms you're trying to use mpremote, which won't work. Use USB Mass Storage Mode instead (see steps above).

## File System Mapping

When in Mass Storage Mode:
- `/Volumes/BADGER/apps/` → `/system/apps/` on badge (your apps)
- `/Volumes/BADGER/assets/` → `/system/assets/` on badge (system files)
- `/Volumes/BADGER/main.py` → `/system/main.py` on badge (boot script)

## Next Steps

After successful deployment:
- Test your app on the badge
- Press HOME button to return to menu
- Make changes locally and redeploy as needed