---
name: add-app
description: Step-by-step guide for adding a new containerized app to Archipelago
disable-model-invocation: true
allowed-tools: Bash, Read, Write, Edit, Glob, Grep
argument-hint: "[app-name]"
---

Add a new containerized app ($ARGUMENTS) to Archipelago.

## Steps

### 1. Create the manifest

Create `apps/{app-id}/manifest.yml` following the spec in `docs/app-manifest-spec.md`:
- `app.id` (kebab-case), `app.name`, `app.version` (SemVer)
- `container.image` (pinned version, **NEVER** `latest`)
- `security`: readonly_root, dropped capabilities, non-root UID > 1000
- `health_check`, `dependencies`

### 2. Add app icon

Place icon at `neode-ui/public/assets/img/app-icons/{app-id}.{png|webp|svg}`

### 3. Create status UI (if no native web UI)

For apps without their own web interface, create a UI container in `docker/{app-id}-ui/` following the patterns in `.cursor/rules/APP-UI-STANDARDS.md`.

Reference implementations:
- Bitcoin UI: `docker/bitcoin-ui/`
- LND UI: `docker/lnd-ui/`

### 4. Update backend

- Add port mapping in `core/archipelago/src/container/docker_packages.rs`
- Add env vars in `get_app_config()` in `core/archipelago/src/api/rpc.rs`

### 5. Deploy and test

- Deploy: `./scripts/deploy-to-target.sh --live`
- Install from marketplace UI at http://192.168.1.228
- Verify it launches and auto-connects to dependencies
- Check logs: `sudo podman logs {container-name}`

### 6. Security review

- Verify readonly root, dropped caps, non-root user
- Check network isolation
- No hardcoded secrets