zaplaunch: Open-Source iOS Launcher for Agents

“Run it on my phone.”

That’s a useful instruction to give a coding agent after it changes your app. You want to pick up the phone, open the screen you were working on, and see how it feels.

zaplaunch is the launcher that makes that one step. Your coding agent, like Codex or Claude Code, runs one command and your iOS app opens on your phone. Today we’re open-sourcing zaplaunch under the MIT license. The repository is public, v1.0.0 is out, and it installs with one line:

curl -fsSL https://raw.githubusercontent.com/tortuga-ai/zaplaunch/main/install.sh | bash

The script checks the download against the release checksums and installs zaplaunch to ~/.local/bin. Running the same command again updates it. You need macOS with full Xcode installed.

Why we built it

An agent can edit a view, explain its changes, and tell you the build passed. You still need to review the result. For an iOS app, that often means picking up your phone and trying it.

Think about a change to a form. The code might look reasonable, but you want to see what happens when the keyboard opens. Can you reach the submit button? Does the screen scroll the way you expect? Is the field you’re editing still visible?

Getting the latest change onto the phone is the setup work before that review, and it happens after every change. If the agent can’t do that step, you do it by hand each time and the loop slows down. zaplaunch gives the agent one command for it, so you ask for a change, the agent launches it on your phone, and you tell it what to fix next.

One command, and the app opens

Here’s what your agent runs, with an example scheme called MyApp. From your Xcode project directory:

zaplaunch run MyApp

zaplaunch builds the change, installs it on your phone, and opens the app. Replace MyApp with your project’s scheme.

If the latest build is already installed, the agent can just open it:

zaplaunch com.example.MyApp

The first time, the agent can list your paired devices and pick one by its name from that output, for example “My iPhone”:

zaplaunch devices
zaplaunch use "My iPhone"

Launch in the right environment

When the app needs to point at a specific backend or mode, the agent passes environment variables at launch with --env KEY=value. Repeat it for more than one:

zaplaunch run MyApp --env APP_ENV=production
zaplaunch com.example.MyApp --env API_URL=https://dev.example.com --env FEATURE_FLAG=true

zaplaunch hands these to the app when it opens. Your app has to read them itself, for example through ProcessInfo.processInfo.environment in Swift. They apply only to that launch, not to later launches from the home screen. If the app is already running, zaplaunch restarts it so the new values take effect.

On your phone, localhost means the phone itself, so a backend running on your Mac needs the Mac’s network address or a tunnel URL.

Let the agent read the console

When the agent needs logs, it relaunches the app with the console attached:

zaplaunch -c com.example.MyApp

Replace the example bundle identifier with your app’s. The console command keeps streaming until it’s stopped, so the agent should run it in the background and read the output.

Works with Codex and Claude Code

For Claude Code, running zaplaunch --skill writes a skill to ~/.claude/skills/zaplaunch/SKILL.md. It tells the agent which command to use for a new change, an app restart, or console output, and what to do about common setup problems.

Codex and other agents that can run shell commands use the same commands. Put the project details in your repository’s AGENTS.md or other agent instructions: the scheme, bundle identifier, project directory, and which phone to use.

Then a request can be as direct as: “Build the changes and run MyApp on my phone using zaplaunch.” The agent has the command and the project context to carry that out.

The phone still needs to be ready

zaplaunch needs a Mac with full Xcode 15 or later and an iPhone running iOS 17 or later (iPads on iPadOS 17 work too). Standalone Command Line Tools aren’t enough. Your project also needs working signing and its own dependencies installed.

Pair the phone over USB, trust the computer, and enable Developer Mode. To work wirelessly, tick “Connect via network” for the phone in Xcode. After that the cable can come out. Keep the phone unlocked for installs. That setup is per Mac, and the agent can’t do it for you.

Those are real limits on the workflow. An agent can run the command, but signing problems or a locked phone can still stop the handoff. Get one successful launch working before making it part of your usual development loop.

zaplaunch also has optional usage reporting, which is off until you opt in. The Claude Code skill tells the agent to ask you first and never assume a yes.

The repository README covers installation and the rest of the commands.

Why we’re open-sourcing it

This is a small piece of how we develop at Tortuga: tell an agent to launch an app on a phone, try the interaction, and bring the observation back into the conversation.

“The keyboard covers the button” is a useful next instruction when it comes from using the current build. zaplaunch helps us get to that observation quickly, every time the code changes. We’re open-sourcing it so other teams building with agents can use the same loop, read the script, and adapt it to their own workflow. Bug reports and focused pull requests are welcome on GitHub.

The next thing I want after a code change is the app in my hand.