Developer SDK

Developer SDK

One place for everything a contributor or an agent needs to build, test, and ship changes to Aphotic. Each section below is one page; start with the one that matches what you are doing.

You want to...	Go to
Drive a stable system daily and test changes in a VM	Contributor Workflow
Build the dev VM (libvirt or Proxmox)	Dev VM
Write a plugin against the plugin system	Build a Plugin, with the plugin SDK guide in the plugins repo
Understand the engine and harness descriptors	Plugin System
See where AI shows up in the shell	Agentic Workflows
Open a PR that passes review	Contributing
Look up any aphotic command	CLI Reference

Build and verify

Two commands cover most of the loop:

• tools/ci/local.sh runs the CI checks in a checkout shaped like GitHub's and prints only what failed, with a rerun: command for each failure. Run it before every push; green there means green for test and bash-syntax. One suite: tools/ci/local.sh --only syntax|sh|py.
• The windowless Quickshell probe. qmllint is not reliable for the shell's QML. Instead instantiate the changed surface with the offscreen platform, for example QT_QPA_PLATFORM=offscreen qs -p <component.qml>. Never run qs -p . on a live desktop: it maps a second bar over your session.

What CI runs on a PR, and how to read a red one, is on the Contributor Workflow page.

A first session

A short order that works: read Getting Started, build a dev VM, install the edge channel in it, break something on purpose, reset the VM, and open a branch for the fix. The branch rules, the test cycle, and what the PR needs to say are on the Contributor Workflow page.

See also

• Architecture — how the repo is laid out
• Theming — how colors flow from the wallpaper into every surface
• Troubleshooting — when something is not working the way the docs say it should