Local development
Start the actual iPolloWork development workflow on macOS, Linux, or Windows.
The repository launcher is the source of truth for local development. It prepares the workspace dependencies and keeps development state isolated from a normal OpenCode profile.
The launcher keeps the UI, Electron shell, server packages, and supported sidecars on the same checked-out revision. It is safer than starting one layer in isolation and guessing the remaining state.
Repository-level dependency and command boundary
Locked dependencies for apps and shared packages.
The `ipollowork` command defines supported local workflows.
What you see and operate
The React work surface used by desktop, browser, and headless workflows.
An isolated data and runtime profile for the native client.
What performs the work
Supported sidecars prepared for development by the launcher.
Filesystem-backed workspace API and runtime adapter boundary.
Requirements
- Git
- Node.js 22 or newer
- pnpm 11 enabled with Corepack
- Bun 1.3.10 or newer for the local Orchestrator sidecar
- Electron build prerequisites for the target operating system
On macOS, install Xcode Command Line Tools with xcode-select --install. On Windows, install Visual Studio 2022 Build Tools with Desktop development with C++ and the Windows SDK.
Start the desktop app
macOS and Linux:
git clone https://github.com/Devin-AXIS/iPolloWork.git
cd iPolloWork
corepack enable
./ipollowork setup
./ipollowork dev
Windows PowerShell:
git clone https://github.com/Devin-AXIS/iPolloWork.git
Set-Location iPolloWork
corepack enable
.\ipollowork.cmd setup
.\ipollowork.cmd dev
Target a specific development surface
| Goal | Command |
|---|---|
| Desktop client | ./ipollowork dev |
| Browser UI only | ./ipollowork dev:ui |
| Headless web workflow | pnpm dev:headless-web |
| Local Cloud connection | ./ipollowork dev:cloud http://localhost:3100 |
| Type checks and desktop tests | ./ipollowork check |
For Windows, substitute ./ipollowork with .\ipollowork.cmd.
What each launcher command does
| Command | Intended outcome | Notes |
|---|---|---|
setup | Install the locked workspace dependencies | Run this after cloning or after a dependency change. |
dev | Start the full desktop development flow | Prepares the supported sidecars, starts the UI, and opens Electron with an isolated development profile. |
dev:ui | Start the browser-oriented UI surface | Useful when the narrow change is in the React app and does not need a native shell check. |
dev:cloud [url] | Start desktop development against a Cloud base URL | Defaults to http://localhost:3100, normalizes the URL, and writes a dedicated development bootstrap record under .ipollowork-dev/cloud/. |
build | Build the workspace artifacts | Use before packaging or when a production-like build failure must be reproduced. |
package:dir | Produce an unpacked desktop artifact | Does not advance the release version. Use it for native verification. |
package | Produce native installer artifacts | Runs the strict release review and checks unless explicitly skipped. It does not commit, tag, or publish a release. |
Cloud development isolation
dev:cloud is a deliberate development mode. It provides the chosen base URL to the app and uses an isolated Electron user-data and runtime path. That prevents a test Cloud session from overwriting normal desktop state. Treat the generated bootstrap file as environment state, not as a secret-sharing mechanism or a production configuration file.
A reliable daily loop
A visual change should be checked in its actual work surface. A server or runtime change should be checked through the client path that consumes it.
- 01Orient
Read the nearest `AGENTS.md`, package scripts, and source owner before changing an unfamiliar layer.
- 02Run one surface
Use `dev`, `dev:ui`, or the relevant package command that exercises the affected runtime.
- 03Verify narrowly
Check the exact UI, server response, package test, or desktop behavior changed by the work.
- 04Run broad gates
Use repository checks and diff validation before handing the change to another person or release flow.
Validate a change
Run the narrow relevant test first. Before a broad handoff, run:
./ipollowork check
git diff --check
./ipollowork check verifies the Traditional Chinese README sync, application type checks, Electron type checks, and desktop tests. It is a repository-wide gate, not a substitute for manually checking an interaction or a changed HTTP route.
Troubleshoot by ownership
| Symptom | First boundary to inspect | What not to assume |
|---|---|---|
| Desktop starts but a local task cannot run | Local server, approval state, and supported sidecar health | A Cloud session can repair a local sidecar or workspace issue |
| Browser UI is correct but native behavior is wrong | Electron shell and desktop bridge | dev:ui proves native lifecycle behavior |
| Cloud sign-in points at the wrong environment | .ipollowork-dev/cloud/ bootstrap state and the configured base URL | A normal desktop profile should be edited manually |
| Package build fails | Package script output, native build prerequisites, and the exact target OS | package publishes anything remotely |
For server configuration and network-boundary checks, continue with Self-hosted topology. For production ownership and recovery gates, continue with Production operations.