A remote build, deploy, release and profiling host for games and apps. Agents and people drive it over HTTP, MCP or a web UI; several devkit servers can be connected and reached through any one of them.
v1 runs on macOS (Xcode, iOS devices and simulators, Instruments, Unity). Windows and Linux hosts follow in v2 and v3.
Build the menu bar app and install it:
app/build.sh --dmg # dist/Devkit.app and dist/Devkit.dmgOpen Devkit.dmg, drag Devkit to Applications and start it. Devkit lives in the menu bar and runs the server; from
its menu:
- Start at Login registers it as a login item.
- Allow Screen Viewing… grants the screen recording permission the web UI's live screen needs. macOS asks for "Devkit", not for Python.
- Copy Owner Token copies the admin token for the first sign-in to the web UI; Open Devkit opens it.
The app keeps its data (tokens, projects, jobs, files) in ~/Library/Application Support/Devkit. It needs Xcode
(which provides /usr/bin/python3) and macOS 14 or later.
build.sh signs with the first Developer ID or Apple Development identity in your keychain (override with
DEVKIT_SIGN_IDENTITY). An ad-hoc signature works too, but macOS then forgets the screen recording permission after
every rebuild.
bin/devkit-server # web UI, API and MCP on http://<host>:7420; data next to the code
bin/install-launchagent # optional: start at login as a LaunchAgent (--uninstall to remove)The first start writes config.json with an owner token (admin). Create further tokens in the web UI under
Settings → Access tokens.
Jobs keep the Mac awake with caffeinate while they run (and the display, for launch and profiling jobs); an idle
devkit lets the Mac sleep as usual.
GET /api/ping returns version, build (Git commit, dirty flag, source SHA-256), disk, and host capabilities.
The Hosts page displays the build identity. app/build.sh embeds build-info.json so the installed app identifies
its source even outside a Git checkout. Comparing only the version is insufficient: multiple builds may share it.
New jobs are refused when free space in the data volume is below min_free_bytes in the existing host config
(default 2 GiB). The worker rechecks before checkout/execution. This is a reserve, not an estimate of build size.
On server startup and while work is pending, the watcher wakes an idle worker. With the exclusive worker lock held,
the worker reconciles interrupted running jobs to failed, preserving artifacts and recording an interruption reason.
It never automatically replays a job, upload, or release. If a recorded PID/process group is still present or cannot
be checked, recovery stops and the queue stays blocked rather than signalling it. Job processes inherit the worker
lock, including checkout commands. Existing workers from an older app should finish before upgrading.
Artifact retention is manual and defaults to a preview:
bin/devkit cleanup --keep-last 50 --older-than-days 30
bin/devkit cleanup --keep-last 50 --older-than-days 30 --applyThe same operation is available to admin tokens through POST /api/cleanup with optional keep_last,
older_than_days, and boolean apply (default false). Cleanup requires an idle worker and drained queue; admission
and deletion are serialized. It removes only canonical artifact directories for terminal jobs older than the age
limit, retaining the newest N terminal jobs and every artifact source referenced by another recorded job's
params.from_job. Job metadata records artifacts_expired; checkout/import caches, credentials, configuration,
job logs, and project data are retained. There is no scheduled deletion.
The plugin/ directory is a Claude Code plugin: it connects the devkit MCP server and adds a skill that teaches Claude
how to build, install, profile and release through it, plus /devkit:status and /devkit:profile.
-
In the devkit web UI, open Settings → Access tokens and create an Operator token for the agent. Settings also shows the address to use.
-
Install the plugin from this repository, in a Claude Code session:
/plugin marketplace add rennerdo30/devkit /plugin install devkit@devkitClaude Code asks for the devkit address (e.g.
http://192.168.1.50:7420) and the token. The token is kept in Claude Code's credential store, not in settings files.From a shell instead:
claude plugin marketplace add rennerdo30/devkit claude plugin install devkit@devkit --config devkit_url=http://192.168.1.50:7420 claude plugin configure devkit@devkit # shows what is still missing; set the token in a session (below) -
Change the address or token later with
/plugin configure devkit@devkit(or/plugin→ Installed → devkit → Configure). -
Check with
/mcp: the server shows up asplugin:devkit:devkit. Try/devkit:status.
Other MCP clients can use the endpoint directly: POST <host>:7420/mcp with Authorization: Bearer <token>.
| Web UI | http://<host>:7420/ |
| MCP | POST /mcp (streamable HTTP, JSON responses), Authorization: Bearer <token> |
| HTTP API | /api/ping, /api/kinds, /api/jobs, /api/jobs/<id>[/log|/artifacts|/cancel], /api/projects, /api/devices, /api/simulators, /api/system, /api/hosts, /api/hosts/<name>/<path> |
| CLI | bin/devkit <verb> (ping, queue, status, list, log, cancel, artifacts, devices, simulators, signing, kinds) |
Job kinds: build, test, archive, release, notarize, deploy, launch, profile, screenshot, crashlogs,
unity, unity-test, aab-sign, mas-pkg, shell, echo. GET /api/kinds documents their parameters.
unity defaults to params.mode: "executeMethod". Existing build requests continue to work. method is a qualified
static Editor method; build_target is optional. quit defaults to true; set it to false for asynchronous gates that
call EditorApplication.Exit themselves. Return a nonzero exit code or throw on compile/gate failure. Project methods
write their output under the DEVKIT_ARTIFACTS environment variable.
Example devkit_queue arguments (also the JSON body for POST /api/jobs):
{"project":"game","repo":"https://github.com/OWNER/GAME.git","commit":"EXACT_SHA","kind":"unity",
"params":{"method":"CompileGate.Run","quit":false,"nographics":true,"timeout":1800}}For Unity Test Framework, use kind: "unity", params.mode: "test", or the equivalent unity-test kind:
{"project":"game","repo":"https://github.com/OWNER/GAME.git","commit":"EXACT_SHA","kind":"unity-test",
"params":{"test_platform":"EditMode","nographics":true,"timeout":1800,
"extra":["-testFilter","Game.Tests","-assemblyNames","Game.Editor.Tests"]}}Use test_platform: "PlayMode" for tests running in the Editor. Test jobs invoke -runTests -testPlatform ... -testResults <artifacts>/TestResults.xml; they exit through the test runner and reject quit and method.
Leave nographics false (the default) for graphics-dependent tests. Unity always receives -batchmode, preventing
interactive Editor windows; callers cannot override it. Editor version comes from ProjectSettings/ProjectVersion.txt
unless unity_version is supplied. The pinned editor must already be installed in Unity Hub's standard Mac location.
The project must contain the Unity Test Framework package and test assemblies.
In the web UI, open a project → Unity build → Unity action. Choose Build or compile gate and an Editor method, or Run tests and EditMode/PlayMode. Set Method exits itself for an asynchronous gate. Build target is optional; graphics stays enabled by default. Test filters and assembly names become separate allow-listed argv values. Xcode defaults on the saved project are not sent as Unity parameters.
extra is an argv list, with these accepted flags only:
- All Unity modes:
-accept-apiupdate,-force-metal,-force-glcore(one graphics API). - Tests:
-testFilter VALUE,-testCategory VALUE,-assemblyNames VALUE. - EditMode only:
-runSynchronously, which excludes multi-frame tests; omit it for full coverage.
Unknown params, managed flags (project path, log path, results path, quit, batchmode), credential flags and malformed
argv are rejected before queueing. For project-specific arguments use params.args, for example
["-gameVersion", "1.0.0"]. Each string permits only letters, digits, underscores, dots and hyphens (128 characters
maximum, one optional leading dash). Managed flags and arguments resembling credentials are rejected. Never submit
secrets in a job: params and argv are visible in job records and logs. extra retains its existing allow-list.
See the official Editor command-line reference
and Test Framework command-line reference.
The existing worker drains FIFO, one job at a time. Unity also holds ~/.local/state/devkit/unity.lock across all
DEVKIT_DATA directories on the host, before checkout and until its process group is stopped and logs are captured.
Run all devkit instances under the supported single host owner account. Other user accounts and manually launched
Editors do not participate in this lock. A child inherits the lock, so worker termination cannot admit another Unity
while that child remains alive. Do not delete the lock file while a runner may be using it.
timeout is a positive number of seconds, capped at 14400 (four hours, the default). The deadline includes slot wait,
checkout and execution. Timeout and cancellation terminate only the job's own process group, escalating to kill after
one second; log draining is bounded. job.log is an artifact for every completed Unity job, including failures and
cancellations. Tests add TestResults.xml and test-summary.json when produced. Missing/malformed XML, an empty test
run, failed results or a nonzero Editor exit fail the job. Partial results remain fetchable after failure/timeout.
Use devkit_artifacts or GET /api/jobs/<id>/artifacts for sizes and SHA-256. Use devkit_read_artifact for XML,
summary and logs, or download GET /api/jobs/<id>/artifacts/<path> (streaming and byte ranges supported).
devkit_log and the existing log API retain live output. Pass the returned host to MCP queries for a forwarded job.
Set params.project_dir for a Unity project below the repository root. It must be a relative directory containing
ProjectSettings/ProjectVersion.txt, even if unity_version is specified. Absolute paths, .. components and symlinks
escaping the checkout are rejected. Omitting it preserves the existing root-project behavior.
For build methods that write outside DEVKIT_ARTIFACTS, params.collect copies repo-relative files or directories
after a successful Editor run (and passing results for test jobs). Each output keeps its last path component.
Missing paths, traversal, absolute or escaping copied symlinks, cycles and artifact-name collisions fail clearly.
Runner outputs (including job.log, job.json and test results) are reserved. Copies preserve symlinks and use APFS
clones where available, with a normal-copy fallback; both obey cancellation and the Unity deadline. The copied tree
is validated before acceptance. Paths are relative to the repo, including when project_dir is set.
{"project":"game","repo":"https://github.com/OWNER/GAME.git","commit":"EXACT_SHA","kind":"unity",
"params":{"project_dir":"unity","method":"Build.ExportIOS","build_target":"iOS",
"args":["-gameVersion","1.0.0"],"collect":["unity/Builds/iOS"]}}Queue archive with target: "ios" and params such as
{"from_job":"SOURCE_JOB_ID","project":"iOS/Unity-iPhone.xcodeproj","scheme":"Unity-iPhone","export_method":"app-store-connect"}
to produce an IPA. Automatic provisioning and the configured asc_api_key authentication continue to work as before.
tvOS exports work the same way. Collect the Unity tvOS directory (containing Unity-iPhone.xcodeproj,
scheme Unity-iPhone), then queue:
{"project":"example","commit":"none","kind":"archive","target":"tvos",
"params":{"from_job":"SOURCE_JOB_ID","project":"tvOS/Unity-iPhone.xcodeproj",
"scheme":"Unity-iPhone","export_method":"app-store-connect","team_id":"ABCDE12345"}}build also accepts target: "tvos" and retains the built app. tvOS archives use generic/platform=tvOS.
Both commands use the same automatic signing, -allowProvisioningUpdates and host asc_api_key authentication
as iOS. The export stays local; this example does not upload to App Store Connect. tvOS simulator and device
installation/launch flows are not included.
An owner can allow environment values for all Unity Editor runs in host config.json:
{"unity_env":{"UNITY_TOOLS_PYTHON":"/path/to/venv/bin/python"}}Only host configuration supplies this allow-list; jobs cannot submit env. Values must be strings without control
characters (maximum 4096 characters). Values whose variable names resemble secrets are masked in Editor output.
The interpreter and its environment must already exist on the build host.
Use a Unity Android build method with collect to retain its unsigned or previously signed AAB, then queue:
{"project":"game","commit":"none","kind":"aab-sign","target":"android",
"params":{"from_job":"SOURCE_JOB_ID","aab":"Android/game.aab",
"keystore_path":"/path/to/signing.keystore","alias":"upload",
"keychain_service":"example-signing","keychain_account":"upload"}}The source job must have succeeded on the same host. aab stays inside its artifacts; the keystore must be a regular
host file outside the job checkout. No checkout or Xcode is needed. A JDK is located using JAVA_HOME, then
/usr/libexec/java_home (or tools on PATH when no Java home is available). The key's store and key passwords must
match the generic password already provisioned in Keychain under the given service/account.
The job rewrites a copy, stripping META-INF/*.SF, *.RSA, *.EC, *.DSA while retaining MANIFEST.MF, signs with
SHA256withRSA/SHA-256, then runs jarsigner -verify -strict -certs, requiring a verified result without warnings.
The signed bundle's certificate must report at least RSA 2048 or EC 256. The password is captured in memory, supplied only through
the signing child's environment and masked from its output; it is never added to argv, job params or artifacts.
The resulting aab-sign.json records the signed AAB's artifact-relative path, lowercase SHA-256, byte size
and lowercase signer_cert_sha256 from keytool (without colons). After signature verification, manifest metadata
comes from bundletool on PATH when present, otherwise from Android SDK aapt2. SDK discovery checks
ANDROID_HOME/ANDROID_SDK_ROOT, or the standard macOS Android SDK location, selecting the highest executable
build-tools version, then falls back to PATH. The aapt2 fallback wraps the bundle's protobuf base manifest in a
temporary ZIP for dump xmltree; it does not dump the AAB directly. The report always includes package,
versionCode (a positive JSON integer), versionName and manifest_source ("bundletool", "aapt2" or null).
Unavailable or invalid identity fields stay null with a manifest_note; parsed minSdk/targetSdk integers are
also included when available. If neither tool is available, identity fields and manifest_source remain null
with a skip note. This kind signs locally and does not upload to a store.
Collect a Unity macOS .app (for example with build_target: "StandaloneOSX" and
collect: ["Builds/macOS"]), then queue a standalone package job on the same host:
{"project":"example","commit":"none","kind":"mas-pkg","target":"macos",
"params":{"from_job":"SOURCE_JOB_ID","app":"macOS/Example.app","profile":"example-store.provisionprofile",
"entitlement_values":{"com.apple.developer.game-center":true,
"com.apple.security.network.client":true}}}The host owner configures config.json (paths here are placeholders):
{"team_id":"ABCDE12345","mas_profiles_dir":"/path/to/mas-profiles"}params.team_id overrides the host team. params.profile is a relative file under mas_profiles_dir;
absolute paths, traversal and escapes through symlinks are rejected. Obtain the profile in the
Developer portal:
Profiles → Mac App Store Connect → the app's App ID, with Game Center enabled if requested, selecting the host's
Apple Distribution certificate. Alternatively use Xcode's account settings → Download Manual Profiles.
Copy the downloaded profile into mas_profiles_dir. This kind uses that profile; it does not create/download
one through the ASC API or infer provisioning from an arbitrary .app without Xcode project context.
The profile is CMS-decoded and checked for macOS App Store distribution (no device list, all-device distribution
or debugging), expiry, team, bundle ID and the selected signing certificate. A final .* App ID wildcard is
expanded to the app's bundle ID; other wildcard forms fail. The profile must authorize Game Center when enabled.
The original profile is embedded at Contents/embedded.provisionprofile before signing a private app copy.
The host keychain needs Apple Distribution (app signing) and Mac Installer Distribution (package signing)
certificates with their private keys. The latter may appear as 3rd Party Mac Developer Installer.
security find-identity must yield exactly one valid identity of each type for the team; missing or ambiguous
matches fail. Developer ID certificates are not accepted. Certificate subject names and tool output stay out of
job logs and reports; only authority types are reported.
An Admin ASC key with the required certificate permissions can use
cloud-managed signing for Xcode exports.
Standalone codesign and productbuild need local identities; a cloud certificate alone does not supply a local
private key. An owner can first export a macOS archive using xcodebuild -exportArchive with an
-exportOptionsPlist containing method: app-store-connect, signingStyle: automatic, and the team, plus
-allowProvisioningUpdates and ASC authentication. Xcode can provision distribution signing with suitable account
permissions; ensure the installer identity and its private key are actually in the host keychain afterwards.
For explicit local setup, create a CSR using Keychain Access, create Mac Installer Distribution in Developer
portal → Certificates, download and import the certificate on the Mac that owns that CSR's private key. Provision
Apple Distribution locally in the same way (or import a securely transferred certificate/private-key identity).
See Apple's Mac packaging guide.
App Sandbox (com.apple.security.app-sandbox=true) is always included. entitlement_values explicitly opts into
boolean capabilities: com.apple.developer.game-center, com.apple.security.cs.allow-jit,
com.apple.security.network.client, com.apple.security.network.server,
com.apple.security.files.user-selected.read-write, com.apple.security.files.user-selected.read-only,
com.apple.security.device.audio-input, com.apple.security.device.camera, com.apple.security.device.usb,
and com.apple.security.print. No extra capabilities are enabled by default. Unknown keys and both forms of
get-task-allow are rejected even when false. Additional capabilities require an explicit change to this allowlist.
Instead of entitlement_values, supply entitlements: "relative/entitlements.plist" from the source job's artifacts.
The same allowlist applies; disabling sandbox fails. Optional com.apple.application-identifier and
com.apple.developer.team-identifier in a supplied plist must match the profile-derived identity. Otherwise these
identity entitlements are generated. hardened_runtime: true enables runtime signing options; it defaults to false.
Entitlements are applied only to the main app. Mach-O code and enclosing code bundles are signed inside-out,
then productbuild --component <app> /Applications --sign <installer-identity> out.pkg packages it.
A successful pkgutil --check-signature out.pkg is required before mas-pkg.json is written. The report records
path, SHA-256, byte size, bundle ID, version, build, app and installer authority types, team, profile name/UUID
and sorted entitlement keys. The effective plist is also retained as MAS-Entitlements.plist.
This checks local profile compatibility and package signing; it does not prove App Store acceptance or launchability.
Gatekeeper spctl, codesign --verify --deep --strict, notarization and launch smoke tests are not run for this MAS
workflow. Upload/validation in App Store Connect remains a separate owner-operated step.
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-test.txt
.venv/bin/python -m unittest discover -s tests -v
node --test tests/test_ui.cjs
node --check web/app.jsSchema tests validate every advertised tool against JSON Schema draft 2020-12 and require all 16 tools, including
devkit_queue, for every role. Tool input schemas use a plain object at the root: Claude's API rejects top-level
allOf, oneOf and anyOf even though they are valid JSON Schema. Unity's conditional rules are enforced by the
server before a job is saved or a worker starts; the queue schema documents them without root combinators.
The runner-only checks can also run without the schema-test dependency:
python3 -m unittest discover -s tests -p test_unity.py -v
python3 -m unittest discover -s tests -p test_runner.py -v
python3 -m unittest discover -s tests -p test_mcp.py -vTests use disposable editor executables and temporary job stores; no credentials, Unity license, Mac, or network are required. POSIX tests exercise real process groups, TERM-resistant processes, deadlines under continuous output, host slot exclusion and the MCP queue → status → artifacts → read flow. Windows runs the argument/result tests and skips POSIX host tests. Native Unity EditMode/PlayMode acceptance must be run on the Mac after the owner updates it.
This change is source-only; no running Mac checkout or service has been changed. Before updating, stop submissions
and let all queued/running jobs become terminal in the web UI. Existing detached workers must finish before restarting.
Keep the same OS account, data directory, existing credentials and service start method. Do not print configuration
or credential files. In the Mac's ~/Development/devkit checkout:
cd ~/Development/devkit
git status --short # stop and preserve any source changes
git fetch origin feature/unity-gates-tests
git log -1 --oneline origin/feature/unity-gates-tests
git branch backup/before-unity-gates HEAD
git switch -c update/unity-gates-tests --track origin/feature/unity-gates-tests
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-test.txt
.venv/bin/python -m unittest discover -s tests -vChoose the restart procedure matching the current installation:
-
Source LaunchAgent:
bin/install-launchagentreinstalls/restartsdev.devkit.serverfrom this checkout. If a custom LaunchAgent suppliesDEVKIT_DATAor other settings, preserve that plist and instead runlaunchctl kickstart -k gui/$(id -u)/dev.devkit.server. -
Manual source server: stop the existing server in its terminal and start
bin/devkit-serverwith the sameDEVKIT_DATA, port and environment as before. -
Menu bar app: Quit Devkit from its menu; the app bundles its own Python sources, so a source checkout update alone is insufficient. Preserve the installed app, run
app/build.sh, then install and start the rebuilt app:backup_dir="$HOME/Devkit-backups/$(date +%Y%m%d-%H%M%S)" mkdir -p "$backup_dir" ditto /Applications/Devkit.app "$backup_dir/Devkit.app" app/build.sh ditto dist/Devkit.app /Applications/Devkit.app open /Applications/Devkit.app
Use the existing signing identity; an ad-hoc rebuild can reset screen recording permission. App data stays at
~/Library/Application Support/Devkit; do not replace or erase it. Run only one installation at a time.
Reconnect/reload MCP so callers receive the new tool schema; initialize must report version 0.6.0 and
devkit_kinds must include unity-test. Verify a self-exiting compile gate without build_target, then one EditMode
and one PlayMode job on exact commits. Fetch XML and job.log; compare artifact checksums. Finally verify a short
timeout and two queued Unity requests. Retain native acceptance evidence separately from the fixture test results.
Rollback source code to backup/before-unity-gates and restart the same installation if needed; retain all runtime data.
Tokens have one of three roles: viewer (read), operator (run and cancel jobs, edit projects, view the screen), admin (also manage tokens and connected hosts). Only SHA-256 hashes of tokens are stored. Traffic is plain HTTP, so use it on a trusted network or put TLS in front of it; an operator token can run arbitrary shell jobs.
On host B, create an operator token named after host A. On host A, open Hosts → Connect a host and enter B's address
and that token. Jobs can then target B explicitly or use host: "auto", which picks an online host running the
target's platform with the shortest queue. Requests are forwarded at most one hop.
Automatic routing also requires the advertised job kind/target, disk readiness, any explicitly requested Unity
editor version, and the device/simulator ID. For additional constraints, send e.g.
"requires":{"xcode":"26.0","sdk":"iphoneos26.0","simulator_runtime":"iOS-26-0"} with host:"auto".
These strings must match advertised capabilities; unity_version is also accepted in requires. Hosts missing
required facts are excluded. Supply params.unity_version or requires.unity_version when automatic placement
must match an exact editor; the router does not fetch a project's pinned commit to discover its editor version.
Requirements filter automatic placement; they do not switch Xcode installations or install SDKs/editors.
CI runs Python regressions and JavaScript checks on GitHub-hosted Linux and macOS runners for this public repository, plus a Swift compilation on macOS. The workflow uses pinned action releases verified on 2026-10-22: checkout 7.0.1 and setup-python 7.0.0, both published 2026-07-20. Tests use temporary stores and command fixtures; native device, signing, Unity acceptance and installed-app updates remain separate checks. Windows and Linux execution hosts remain outside the macOS v1 implementation.
bin/devkit job queue, worker and CLI
bin/devkit-server HTTP server: web UI, API, MCP, peers
lib/ job kinds, host facts, tokens, peers
web/ web UI (plain HTML, CSS, JS; English and German)
app/ macOS menu bar app (Swift) and its build script
launchd/ LaunchAgent template for running without the app
plugin/ Claude Code plugin (MCP connection, skills)
.claude-plugin/ plugin marketplace manifest
Data (config.json, tokens.json, projects.json, jobs/, artifacts/, ...) lives in $DEVKIT_DATA if set
(the app sets it to ~/Library/Application Support/Devkit), otherwise next to the code. DEVKIT_PORT overrides the port.