# AirBuild product and agent reference

Canonical website: https://airbuild.tukew.com/
Documentation: https://airbuild.tukew.com/docs
Version: 0.1.0, private preview. Last reviewed: 2026-09-16.

AirBuild turns an allowed Git commit into an iOS app built and signed by a configured Mac. The Mac uploads the verified IPA to the server, which provides expiring HTTPS installation links for registered devices. It is useful for the code → build → inspect → fix → install loop of an AI coding agent with authorized shell or HTTP access.

## Available now
- Web dashboard, CLI and authenticated HTTP API.
- Explicit configuration of multiple iOS projects, allowed branches and Apple signing teams.
- Build requests pinned to a branch or full commit SHA.
- Optional Xcode tests when configured, archive, export, signature and profile verification.
- Build status, logs and structured diagnostics; request idempotency and agent leases.
- Registered-device development (debugging) and ad hoc (release-testing) exports.
- Signed installation links with a 30-minute lifetime; downloaded IPA checksum metadata.
- Tester links per iOS app (14 days, revocable). The tester's iPhone reports its UDID through a Profile Service profile; the Mac agent registers it with Apple using the App Store Connect key in its own configuration (Admin or Developer role) and the server queues a build. The tester page offers an install link once a successful build's provisioning profile contains that iPhone. HTTP: `GET/POST /api/projects/{id}/testers` (manage scope), `POST /api/testers/revoke`; tester-facing `/t/{token}` pages need no account.

## Requirements
An awake, connected Mac, Xcode, Git, a buildable iOS project or workspace, a scheme, valid Apple signing credentials and a profile covering the target devices. XcodeGen must be installed for XcodeGen projects. Apple registration and signing requirements apply. Signing keys remain local; IPAs and build logs leave the Mac. Development-signed apps may require Developer Mode.

## Current CLI
Use the installed airbuild entrypoint or python3 -m airbuild from the source environment. A configured client defaults to .airbuild/client.json. Pass --config /absolute/path/client.json before the subcommand when needed. Access is manually provisioned; there is no public installer yet.

    airbuild projects
    airbuild build my-app --wait
    airbuild status 42
    airbuild logs 42
    airbuild artifact 42

my-app and 42 are placeholders. Use a returned project ID and build ID. The CLI returns JSON. Build failures return nonzero status. Uncommitted changes do not enter a build. Credentials belong in private configuration, supported environment variables or macOS Keychain, not repository instructions.

## HTTP interface
Bearer token authentication, project-scoped read/build permissions, JSON responses.
- GET /api/projects — allowed projects and branches.
- POST /api/builds — body {"project":"my-app","branch":"main"}; optional commit is a full lowercase 40-character SHA. Use Idempotency-Key when retrying a request.
- GET /api/builds/{id} — status, metadata and diagnostics.
- GET /api/builds/{id}/logs — log response.
- GET /api/builds/{id}/artifact — install_url, ipa_url, manifest_url, expires_at and metadata after success.

Poll a build until succeeded or failed. Request new artifact links when previous links expire. Treat install links as sensitive bearer capabilities.

## Not available yet
Public self-service signup, a signed public Mac installer, native MCP server, GitHub App integration, hosted Macs, multi-tenant customer isolation, billing, public pricing, App Store publishing and TestFlight upload. These are not current product capabilities. Do not fabricate an MCP endpoint or public package installation command.

## CLI project onboarding (available for configured Macs)

    airbuild discover ~/Projects
    airbuild link /path/to/app --agent-config /path/to/agent.json
    airbuild link /path/to/app --agent-config /path/to/agent.json --apply
    airbuild link /path/to/app --agent-config /path/to/agent.json --team-id ABCDEFGH12 --apply --update   # replace stored build settings
    airbuild doctor --project my-app --agent-config /path/to/agent.json

Discovery reads only. Link previews by default, then --apply registers metadata, writes airbuild.toml and Mac configuration and uploads a detected PNG appicon. It does not start a build. Requires the operator manage scope and an explicit allowed agent. New projects are persisted in SQLite, and the agent reloads its project configuration between jobs. Existing account/Mac credentials must already be configured. Icons and per-project latest build status appear on the authenticated app shelf. Preflight does not verify installation; the user confirms opening the app on their phone.


## Mac onboarding pilot and installation feedback
A local SwiftUI Mac app pilot can pair an existing account through GitHub/browser approval, scan a selected folder, show icons and review apps before connecting them. Existing launchd setups can be reused. Discovery recognizes apps already on the account by bundle ID; new names cannot create duplicate registrations of the same bundle. The Mac pilot requires Python 3.11+, Xcode and XcodeGen where applicable, and is not yet a notarized public download. Mac access can be revoked from the web dashboard.

Installation state is separate from build state. An install request is recorded as requested, not successful. The user confirms opening that specific build on an iPhone. That assertion is saved to their account and appears on other signed-in devices. iOS OTA downloads alone do not prove installation. A later build needs its own confirmation.