AppDock

AppDock is a lightweight, local-first dashboard for organizing and running web apps, developer tools, and repositories on a Windows PC.

It discovers explicit appdock.json manifests, shows process and health state, preserves app order, captures bounded log tails, and provides safe start/stop/restart controls. Apps can be registered from an existing local folder or—through an Advanced flow—cloned from a public GitHub repository and reviewed before registration.

AppDock never runs a newly added app automatically. Review the displayed command and trust the app's source before pressing Start.

Highlights

• Local-first: AppDock binds to 127.0.0.1 by default and stores state on your computer.
• Portable: Python 3.11+ standard library only; no runtime packages to install.
• Explicit registry: only folders with valid manifests become apps.
• Two onboarding paths: register a downloaded folder or import a public GitHub repository from the Advanced view.
• Preview before trust: inspect the resolved directory, command, URLs, and manifest before registration.
• Safe process launch: argument arrays with shell=False; no arbitrary shell-command field.
• Health-aware controls: distinguish stopped, running, healthy, unhealthy, and crashed apps.
• Stable and Beta update channels: Stable is the default. Users can explicitly opt into immutable numbered Beta prereleases from the Updates page without changing the verified update pipeline.
• Update notifications: quietly check the selected GitHub Release channel after startup and show a non-blocking banner/badge when a newer eligible release is available. Checks never download or apply updates.
• Explicit updates: Update now uses a channel-bound confirmation digest, trusted checksum-verified assets, safe staging, backup/restart/rollback, and expected-version health verification. Windows is the supported one-click update target.
• Optional LM Studio: inspect installed/running models and manage exact instances through the local lms CLI when installed; AppDock itself has no network dependency for this integration.
• Windows-friendly: guided installer, optional startup shortcut, portable ZIP releases, CI, and rollback-oriented updates.

Requirements

• Windows 10 or 11
• Python 3.11 or newer (py -3.11 --version)
• Git only if you want AppDock to clone GitHub-hosted apps

The core server also runs on macOS and Linux, but the first supported installer and updater target is Windows.

Quick start

Recommended: Windows release

1. Download appdock-windows.zip and SHA256SUMS.txt from the latest release.
2. Verify the checksum as described in Windows installation.
3. Extract the ZIP.
4. Run:

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1

5. Open http://127.0.0.1:8765.

Run directly from a clone

git clone https://github.com/eWOOD29/appdock.git
cd appdock
py -3.11 appdock.py --host 127.0.0.1 --port 8765

For an isolated test profile:

py -3.11 appdock.py --data-dir "$env:TEMP\appdock-demo"

Where AppDock stores data

Installation files and user data are separate so updates do not overwrite your apps or configuration.

Purpose	Windows default
Installed program	%LOCALAPPDATA%\Programs\AppDock
User data	%LOCALAPPDATA%\AppDock
Registry manifests	%LOCALAPPDATA%\AppDock\registry
GitHub-installed apps	%LOCALAPPDATA%\AppDock\apps
Logs/order/update staging	%LOCALAPPDATA%\AppDock\runtime and related data folders

Override the data directory with --data-dir PATH or APPDOCK_DATA_DIR. Do not commit the data directory to source control.

Add an app

Existing local folder

1. Add an appdock.json file to the app's root.
2. In AppDock, open Add app → Local folder.
3. Enter the folder path and choose Preview.
4. Review the resolved command and paths.
5. Choose Register. The app remains stopped until you explicitly start it.

Public GitHub repository

1. Open Add app → Advanced: GitHub.
2. Paste a canonical public URL such as https://github.com/owner/project.
3. AppDock clones into a private staging directory and validates the root manifest.
4. Review the preview, then register it.
5. Press Start only after you trust the repository and command.

GitHub import accepts only public https://github.com/<owner>/<repo> URLs. It rejects credentials, query strings, fragments, SSH URLs, alternate hosts, and nested paths.

Manifest example

{
  "schema_version": 1,
  "id": "sample-app",
  "name": "Sample App",
  "description": "A small local web app",
  "command": [".venv/Scripts/python.exe", "-m", "sample_app"],
  "cwd": ".",
  "port": 8787,
  "health_url": "http://127.0.0.1:8787/health",
  "local_url": "http://127.0.0.1:8787"
}

Commands are JSON arrays, not shell strings. See the complete manifest reference.

Make your own repository AppDock-ready

Add appdock.json at the repository root and include an Add to AppDock section in your README:

## Add to AppDock

In AppDock, open **Add app → Advanced: GitHub**, paste this repository URL,
review the manifest and command, then register it.

A repository should also document its own prerequisites and setup. AppDock does not silently install dependencies or run setup scripts.

Updates

Open the navigation drawer and select Updates, or follow the non-blocking availability banner. The update channel defaults to Stable. Beta (pre-release) is an explicit opt-in for numbered GitHub prereleases such as v0.2.2-beta.1; AppDock never installs raw develop branch bytes. Switching back to Stable never forces a downgrade. AppDock contacts GitHub Releases and ordinary connection metadata (such as request IP and user agent) may be processed by GitHub. A check never downloads or applies anything. Update now is explicit and downloads only the expected release assets from the selected channel, verifies SHA256SUMS.txt, checks the ZIP for unsafe paths, stages a backup, preserves the separate mutable user data directory, and restarts AppDock. Both channels use the same verification and rollback pipeline. Windows is supported for one-click application. A development clone should use Git (git pull) rather than one-click update. See Update design and recovery.

Optional LM Studio integration

LM Studio is optional. If the local lms executable is installed, the LM Studio page can show models from lms ls --json, loaded instances from lms ps --json, and expose bounded load settings plus exact-instance unload. AppDock finds APPDOCK_LMS_PATH, standard per-user LM Studio bin locations, then PATH; it does not send model data or require a network connection. If LM Studio is absent, the page explains the optional integration and links to the public CLI documentation.

Documentation

• Windows installation
• Migrating an existing setup
• Usage guide
• Manifest reference
• Architecture and trust boundaries
• Publishing AppDock-ready apps
• Privacy
• FAQ
• Troubleshooting
• Updates and rollback
• Security policy
• Contributing
• Changelog

Development

main is the Stable integration branch. Ongoing release work is integrated on develop; numbered Beta prereleases are cut only from commits contained in develop, then promoted to main after final validation.

py -3.11 -m unittest discover -s tests -v
py -3.11 -m compileall -q appdock.py tests scripts
py -3.11 scripts/privacy_scan.py
py -3.11 scripts/check_docs.py
node --check static/app.js

Run the development server with disposable data:

py -3.11 appdock.py --data-dir "$env:TEMP\appdock-dev" --port 8765

Security model

AppDock is a local control plane, not a sandbox. Starting an app runs its declared executable with your Windows account's permissions. AppDock reduces accidental command injection and path confusion, but it cannot make untrusted code safe. Read SECURITY.md before importing repositories you do not control.

License

MIT