CUTIP Desktop¶

Visual companion app for CUTIP — Container Unit Templates in Python.

Workspace management, artifact inspection, DAG visualization, container control, and observability in a native desktop shell.

Download¶

Grab the latest release for your OS from Releases.

Platform	Artifact
macOS	`.dmg`
Windows	`.exe` (NSIS installer)
Linux	`.AppImage`

Requires: Docker or Podman installed on the host.

Features¶

Register and browse CUTIP project workspaces
DAG visualization of artifact relationships (groups, units, cards)
Container, image, volume, and network management
Interactive container terminal (exec into running containers)
YAML artifact inspection with Monaco editor
Observability log viewer with filtering and auto-scroll
Disk usage analysis with cleanup actions
Splash screen with progress bar on launch

Architecture¶

Electron (native window)
  └── spawns PyInstaller backend binary (random port)
        ├── FastAPI serves React static files (same-origin)
        ├── REST API + WebSocket endpoints
        └── imports cutip library directly (no subprocess)

Frontend: React 18 + TypeScript + Vite + MUI v6 + Zustand + @xyflow/react + Monaco Editor
Backend: FastAPI + SQLAlchemy (async) + SQLite
Launcher: Electron — spawns backend, opens BrowserWindow, kills backend on quit
Auth: GitHub OAuth2 with JWT (optional — app works without login)

Development¶

Prerequisites¶

Python 3.11+
Node.js 20+
uv (Python package manager)
Docker or Podman (for container management features)

Run the app (native, no Docker)¶

git clone https://github.com/joshuajerome/cutip-desktop.git
cd cutip-desktop

# Terminal 1 — backend
cd backend && uv run python -m uvicorn app.main:app --reload --port 8000

# Terminal 2 — frontend
cd frontend && npm run dev

# Terminal 3 — electron shell (optional)
cd electron && npm start

Service	URL
Frontend	http://localhost:3000
Backend	http://localhost:8000/api/health
Swagger	http://localhost:8000/docs

The Vite dev server on :3000 proxies /api requests to the backend on :8000. Both hot-reload on file changes.

Backend tests¶

cd backend && uv run python -m pytest tests/ -v

Frontend lint¶

cd frontend && npm run lint

Production build¶

python scripts/build.py          # PyInstaller + Vite + electron-builder
python scripts/build.py --clean  # clean first

Output lands in dist/ (gitignored).

Environment¶

JWT_SECRET_KEY and FERNET_KEY are auto-generated on first startup. Optional variables:

Variable	Purpose
`CUTIP_DESK_GITHUB_CLIENT_ID`	GitHub OAuth app client ID
`CUTIP_DESK_GITHUB_CLIENT_SECRET`	GitHub OAuth app client secret
`VITE_GITHUB_CLIENT_ID`	Same client ID, for the frontend

Branch Model¶

integration       (default, protected)
  <- staging      (protected, integration gate)
      <- feat/*   (features, deleted after merge)
      <- bug/*    (fixes, deleted after merge)

Release branches: release/vX.Y.Z. Capabilities start at cap030. See capabilities.

License¶

MIT