# Startup Panel

Manage Windows background tasks across computers from **https://tasks.wputopia.com**. Each computer runs one local agent that restores enabled tasks after Windows sign-in.

To register a project, tell its agent:

> Follow https://tasks.wputopia.com/prompt and register this project's required background tasks.

The guide covers installation, updates, pairing, registration, verification, and the project rule. Requests to read or review it remain read-only; sending a URL does not expand the requested scope.

## Quick access

| Purpose | Entry |
| --- | --- |
| Shared dashboard | https://tasks.wputopia.com |
| Open and sign in on the main computer | Desktop: **Startup Panel.bat** |
| Local dashboard | **Local Startup Panel.bat** or **Open Panel.cmd** |
| Main computer's installation | `D:\Projects\StartupPanel` |
| Agent instructions | https://tasks.wputopia.com/prompt |
| Private source | https://github.com/wputopia/StartupPanel |

Use each computer's actual installation path in the commands below.

## Install and pair once per computer

Requirements: Windows, Python 3.11+ with `py -3`, Git, and access to the private repository. Reuse an existing installation.

For a new installation, authenticate Git, then clone into an unused permanent folder:

```powershell
$InstallRoot = Join-Path $env:LOCALAPPDATA 'StartupPanel'
if (Test-Path -LiteralPath $InstallRoot) { throw 'Inspect the existing installation first.' }
git clone --branch main https://github.com/wputopia/StartupPanel.git $InstallRoot
$Panel = Join-Path $InstallRoot 'panel.cmd'
& $Panel connect --url 'https://tasks.wputopia.com' --code '<pairing-code>' --name $env:COMPUTERNAME
```

Get the pairing code from **Add a computer** in the signed-in dashboard. It expires after 15 minutes and works once. Alternatively, run **Setup Computer.cmd** in the installation folder.

Pairing installs automatic startup after Windows sign-in. Wait about 20 seconds for the computer to appear Online. Keep the installation and Python paths stable. The browser and CMD window can be closed.

To reinstall startup, run `panel.cmd install` or **Install Startup.cmd**. The installer uses the current user's **StartupPanel** scheduled task, with **StartupPanel.lnk** in the Startup folder as a fallback. `startup.json` records the method.

## Update

Each computer uses its own GitHub access:

```powershell
$Panel = 'D:\Projects\StartupPanel\panel.cmd'
& $Panel version
& $Panel update --check
& $Panel update
```

Updates fast-forward `main`, restart the agent when needed, and preserve tasks, pairing, logs, and intentional pauses. Local edits, the wrong branch, or divergent commits block updating rather than being overwritten. Updates run when requested, not on a forced background schedule.

The canonical private repository is owned by **wputopia**. Existing Git installations pointing to a previous owner must follow the repository-move steps in [/prompt](https://tasks.wputopia.com/prompt) before updating. Keep the same installation folder and pairing.

For an older ZIP installation without `.git`, follow the migration steps in [/prompt](https://tasks.wputopia.com/prompt). Preserve `tasks.json`, `state/`, `logs/`, and `startup.json`. Never run duplicate agents or copy credentials between computers.

## Rule for every project

Save this in the project's `AGENTS.md`:

> For every new, changed, or retired background/recurring task, follow https://tasks.wputopia.com/prompt. Check/update the local agent, maintain startup-task.json, and register/update/remove the task on its running computer. Before handoff, verify status, logs, Windows sign-in startup, and fresh cloud sync. Preserve intentional pauses and avoid duplicate startup mechanisms.

The standalone copy is [ORCHESTRATOR-RULE.md](ORCHESTRATOR-RULE.md). Agents should report the computer, agent version, task IDs, definition path, commands, and verification results, including any blocker or absence of required tasks.

## Register a task

Keep `startup-task.json` in the project. Replace the example values with the real paths and foreground command:

```json
{
  "id": "my-project-watcher",
  "name": "Project watcher",
  "project": "My project",
  "cwd": "D:\\Projects\\my-project",
  "command": "npm run watcher",
  "mode": "service",
  "enabled": true
}
```

Run on the computer hosting the task:

```powershell
& $Panel register 'D:\Projects\my-project\startup-task.json'
& $Panel status
& $Panel logs my-project-watcher
```

Registration adds or updates by ID. Re-register after changing the project's JSON. Identical settings keep the current process; changed settings may restart it. Use distinct IDs for multiple tasks, or register a file containing `{"tasks": [...]}`.

Use `service` for continuous processes. Use `interval` for scripts that finish, with `interval_seconds` set to the delay after each run. Runs never overlap; missed runs while the computer is off are not replayed.

Templates: [service](examples/startup-task.json), [recurring script](examples/recurring-task.json).

## Controls and recovery

| Action or event | Result |
| --- | --- |
| Windows sign-in | Agent starts and restores enabled tasks |
| Service exits, including code 0 | Restarts with retry delays of 2–60 seconds |
| Supervisor crashes | Guardian attempts recovery |
| **Start** / **Restart** | Enables the task and starts/restarts it |
| **Stop** | Ends the process tree and saves the paused state across reboots |
| **Logs** | Requests the latest 16 KB from the computer |
| `remove <id>` | Stops and unregisters; keeps project files and logs |
| **Disconnect computer** / `disconnect` | Removes cloud access; local tasks continue |
| Health check fails while process is alive | Flags it; does not restart it |
| Internet disconnects | Local supervision continues |
| Computer is off or not signed in | Tasks cannot run |

CLI commands: `cloud`, `open`, `status`, `start <id>`, `stop <id>`, `restart <id>`, `logs <id>`, `remove <id>`, `disconnect`.

Computers sync about every 20 seconds; the dashboard refreshes every five seconds. After 90 seconds without a report, a computer appears offline and controls are disabled. Remote commands expire after two minutes. If a result is uncertain, check current status before retrying.

## Task fields

| Field | Meaning |
| --- | --- |
| `id` | Stable, unique lowercase ID; letters, digits, dots, underscores, hyphens; use a project prefix |
| `name` / `project` | Display labels |
| `cwd` | Existing absolute working directory |
| `command` | Windows cmd command; call `powershell.exe` explicitly for PowerShell |
| `enabled` | Defaults to true; preserve intentional false settings |
| `mode` | `service` or `interval` |
| `interval_seconds` | Delay after each run; default 60, minimum 5 |
| `startup_delay_seconds` | Initial delay; default 0; explicit Start/Restart is immediate |
| `timeout_seconds` | Ends the process tree after this duration; 0 means unlimited |
| `env_file` | Absolute or relative to cwd; simple KEY=value, quotes, and export supported; no variable expansion or inline comments |
| `health_url` | Local HTTP(S) check, about every 10 seconds |
| `health_port` | TCP check on 127.0.0.1; health_url takes precedence |

Commands must stay in the foreground and work without an interactive terminal. Use the project's virtual-environment Python path; put multiline logic in a script. Keep secrets in environment files, outside commands and committed definitions. Stop forcibly ends the process tree.

Missing project folders or environment files make the affected task retry. Invalid central `tasks.json` edits leave current processes running and report an error until fixed.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| Computer missing or Offline | Power, Windows sign-in, network, pairing, and **Open Panel.cmd** |
| Task missing from cloud | Local `status`, cloud connection, and a fresh sync |
| Repeated restarts | Logs, command/cwd, interpreter, dependencies, environment, and occupied ports |
| Task stays Stopped | Start it if the saved pause is no longer wanted |
| JSON changes have no effect | Re-run `register` |
| Dashboard requests a key | Use the main computer's desktop launcher; the owner can also sign in with the private admin key |
| Installation or Python moved | Re-run **Install Startup.cmd** and update project paths |
| Pairing revoked | Run `disconnect`, then pair with a new code |

Signing out of the dashboard does not stop tasks or unpair computers. To disable agent startup, disable the **StartupPanel** scheduled task or remove the fallback **StartupPanel.lnk**. Use Stop to pause individual tasks.

## Files and privacy

- `tasks.json`: central registrations; also keep project-owned definitions and backups.
- `state/`: private control/pairing data. The main computer's `cloud-admin.json` contains the admin key; never commit or share it.
- `logs/`: about 8 MB per task; the local viewer shows the latest 64 KB.
- `startup.json`: Windows startup configuration.

The cloud receives task names, project names, status, and basic process details. Commands, working directories, and environment files remain local. Logs upload only on request and are stored with command results. The dashboard shows the last day's control requests. Release packages exclude runtime state and credentials.

Deployment notes: [cloud/README.md](cloud/README.md). Agent tests: `py -3 -m unittest discover -s tests -v`; tests use temporary registries and ports.