From your repository
to your iPhone.

Connect a Mac and find your apps

The local AirBuild for Mac pilot guides you through GitHub login, browser approval of a temporary code, folder selection, app review and connection. Existing operators can choose Use running Mac setup to reuse their background agent and projects. Existing apps are recognized by bundle ID.

The pilot requires macOS 13+ on Apple Silicon, Python 3.11+, Xcode and XcodeGen where applicable. It is supplied locally; a signed, notarized public installer is not available yet. Keep the Mac app open while its agent runs, or retain your existing background agent. Disconnect a paired Mac using Connect a Mac in the dashboard.

What a project needs

• An awake, connected Mac with Xcode and valid signing credentials.
• A Git repository with the app source committed on an allowed branch.
• An Xcode project or workspace, buildable scheme, bundle identifier and Apple team ID. XcodeGen projects are supported when XcodeGen is installed.
• A provisioning profile that covers the intended devices and distribution method.
• Separate access credentials for the build operator and the Mac agent.

The server stores project metadata and access scopes. The Mac agent stores repository locations, build settings and any required local configuration paths. Signing keys stay on the Mac. Build scripts and package dependencies execute on that Mac, so only connect code you trust to run there.

Current setup process

1. The operator provisions access and a server endpoint.
2. Use discover and link to review and connect the app to your configured Mac. Your operator credential needs the manage scope and permission for that agent.
3. Check Xcode, signing and device provisioning; then start the agent on the Mac.
4. Request the first build and inspect its result before sharing an install link.

Read-only folder discovery and explicit CLI linking are available. Browser account pairing and a Mac menu bar installer are still planned.

Discover and connect a project

Run these commands in the installed AirBuild environment. Discovery reads the chosen folder, skips build caches and does not register or build anything.

airbuild discover ~/Projects

# Preview one app; use --scheme if several apps are found.
airbuild link /path/to/app --agent-config /path/to/agent.json

# Connect only after reviewing the preview.
airbuild link /path/to/app --agent-config /path/to/agent.json --apply

# Check the linked app, then request its first build.
airbuild doctor --project my-app --agent-config /path/to/agent.json
airbuild build my-app --wait

Pass --config /path/to/client.json before the subcommand if the client configuration is elsewhere. Use --id, --name, --scheme, --branch, --team-id or --bundle-id to resolve detected settings.

Linking registers app metadata, stores the local Mac configuration and creates airbuild.toml in the app directory. A detected PNG appicon is uploaded through a protected project endpoint. App source and signing keys are not uploaded by link. The Mac agent loads newly linked projects between builds. Existing conflicting settings are rejected unless you pass --update, which replaces the stored build settings (team ID, bundle ID, branch, scheme) of that project; an interrupted link can be repeated to finish setup. Team IDs are trimmed and must be 10 letters or digits.

The initial flow requires an already configured account and agent. The account needs a manage scope and an explicit managed_agents allowlist. This is project onboarding for the private preview, not public SaaS account signup. The discovery command uses XcodeGen to inspect project.yml files and macOS plutil for Xcode project files. It does not run build scripts.

A successful preflight means the checked prerequisites were found. Only a real signed build verifies the export and profile, and the developer still needs to install and open it on a registered iPhone. The dashboard can record your confirmation in the current browser; it cannot detect installation automatically.

Use AirBuild from an AI coding agent

An agent needs permission to invoke the installed CLI or make HTTP requests. AirBuild does not depend on a particular editor or model. This is a generic shell/API workflow, not a claim of a native integration with every coding product.

From the configured AirBuild environment, use the existing CLI. Replace my-app with a project ID from projects, and replace 42 with the returned build ID.

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

If the console entrypoint is not installed, use python3 -m airbuild from the source environment. The default private client config is .airbuild/client.json. For another working directory, pass --config /absolute/path/client.json before the subcommand.

The feedback loop

1. Discover configured projects and select an authorized branch.
2. Commit your intended changes. AirBuild does not build an editor’s unsaved or uncommitted working tree.
3. Request a build. Keep the returned build ID and use a stable idempotency key when retrying the same request.
4. Read status until it is succeeded or failed. On failure, retrieve logs and diagnostics before proposing a fix.
5. After success, request fresh artifact links and hand the installation step to the developer.

Keep credentials in private configuration, an environment variable or the supported macOS Keychain configuration. Do not paste credentials into repository instructions or build logs. Read-only and build permissions can be scoped to specific projects.

MCP status

A native Model Context Protocol server is planned, but no MCP endpoint is available in this release. Use the CLI or HTTP API today. Do not configure a guessed /mcp URL.

Current HTTP API

The authenticated API uses bearer tokens and returns JSON. Use your provisioned server URL. The examples below use AIRBUILD_TOKEN from the local environment; never substitute a real token into published documentation.

curl https://airbuild.tukew.com/api/projects \
  -H "Authorization: Bearer $AIRBUILD_TOKEN"

curl https://airbuild.tukew.com/api/builds \
  -H "Authorization: Bearer $AIRBUILD_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-app-change-001" \
  -d '{"project":"my-app","branch":"main"}'

Write access requires the build scope and access to the selected project. Agent credentials have a separate scope. Browser sessions also use CSRF protection. An install URL is a temporary bearer capability: anyone holding it may access the artifact until it expires.

Build states are queued, fetching, testing (when configured), archiving, exporting, uploading, succeeded and failed. Builds can skip optional stages. The artifact response includes manifest_url, ipa_url, install_url, expires_at and metadata.

Know when installation is complete

After requesting installation, AirBuild shows Confirm installation. Open the app on your iPhone, return to the build and choose I opened the app on my iPhone. The shelf then shows Installed · confirmed by you, saved to your account for that specific build. You can undo a confirmation or report that installation failed. iOS does not send this page an installation receipt; downloading an IPA is not treated as success.

iPhone installation and Apple signing

AirBuild currently supports registered-device development and ad hoc exports through Xcode’s debugging and release-testing methods. The agent verifies the app signature, provisioning profile and signing expiry before uploading. Installation still depends on the target device being covered by the profile and on valid Apple signing credentials.

The web dashboard requests fresh install links with a 30-minute lifetime. Open the link on the intended iPhone and follow the device’s installation prompts. Development-signed apps may require Developer Mode. AirBuild does not bypass Apple’s signing or device-registration rules.

See Apple’s registered-device distribution guide and ad hoc provisioning instructions for the requirements that apply to your account and export method.

Current scope and limitations

• Private preview with manually provisioned accounts and Macs; CLI project discovery/linking is available, but public account onboarding is not.
• Builds run on a configured Mac, not on hosted macOS infrastructure. An offline or sleeping Mac cannot pick up a build.
• The current deployment is designed for a trusted operator environment. It is not a released multi-tenant service for unrelated customers.
• Uncommitted project changes are not included. Required ignored configuration files need an explicit local mapping.
• No native MCP server, continuous folder watcher, Mac installer, GitHub App, TestFlight upload, billing or public pricing yet.
• No guarantee that an arbitrary Xcode project builds successfully. Its dependencies, scheme and signing must be configured correctly.

Last reviewed: 16 September 2026. See the machine-readable documentation index and plain-text product reference.