Quickstart: Codex on Macswarm

Before you start

• Macswarm is a macOS sandbox for the Agents API. Linux sandboxes from other providers keep working; Codex picks Macswarm when a task needs Xcode or a Simulator.
• Model usage is billed by OpenAI to your account. Macswarm bills the Pod-hours.
• Repositories must be reachable from the Pod over HTTPS or SSH. Pods only make outbound connections, to api.openai.com and your git host.

1. Create the webhook in Macswarm

1. Sign up or sign in.
2. Open Environments and choose Connect Codex. Pick a region (EU or US).
3. Copy the webhook URL. It is unique to your account and can be rotated at any time.

2. Register it with the Agents API

Paste the URL into your Agents API environment settings as the sandbox webhook. From then on, Codex can request a Macswarm Pod for a session. Add the deploy key or GitHub App that lets Pods clone your repositories, and the secrets your builds need.

3. Give Codex a task that needs a Mac

Start a Codex session from the Codex app or your workflow and pick the Macswarm environment:

Build Tidewater for an iPhone Simulator, tap through onboarding and attach a screenshot of every screen.

A clean Pod boots from the warm pool, Codex builds with xcodebuild, leases a Simulator, drives the app through XcodeBuildMCP and attaches the screenshots. Commits are attributed to the developer who started the session.

4. Several agents, one Pod

More Codex sessions from the same environment share your Pod in separate git worktrees. Claude Code sessions can share the same Pod too; the build queue and the Simulator pool do not care which agent is asking. Two to three active agents per standard Pod are guaranteed. See Limits and queues.

5. Finish

Sessions commit and push before they end; leftover changes go to a rescue branch. Ten minutes after the last session the Pod is destroyed and the meter stops.

Troubleshooting

• Codex never asks for a Mac. Check that the webhook is saved in the Agents API environment and that the task actually needs macOS; Linux tasks keep using your other sandboxes.
• Clone fails. The git host must accept the key or App you added. Pods have no inbound network.
• Builds queue. Two concurrent xcodebuild runs per Pod. Start another Pod or let the queue drain.

Next: What is inside a Pod.