Pocketful

Pocketful is a single-user, self-hosted server for signing Apple Wallet passes, built as an Abdeen Labs internal tool with public source. You just describe the pass you want—a loyalty card, event ticket, or coupon—to an AI agent. The agent turns your prompt into a structured spec and sends it to Pocketful over MCP (though a regular script can hit the REST API directly too).

Once Pocketful gets the spec—layout, text fields, colors, barcodes, and source images—it validates everything, crops each image for its slot, renders the exact sizes Wallet expects, and signs the .pkpass bundle in memory using the Apple credentials on your server. You get back a temporary download link you can tap on your iPhone to add the pass, and if you have Hark hooked up, the link also arrives as a notification.

If you make a pass updatable, Pocketful assigns it a permanent serial number and saves the spec. Later on, your agent can pull that spec, tweak it, and push a full replacement. Pocketful checks and re-signs it, then pings registered iPhones via Apple’s Wallet update protocol to pull the new version.

Both the management API and the MCP endpoint use a single bearer token. Any agent or script with that token can create passes and inspect, update, or delete stored ones. Because it’s designed as a personal server for one person, there are no multi-user accounts or permission levels—just rate limiting on the API, MCP, and Wallet endpoints, and auth checks before the server accepts heavy image uploads.

People downloading a pass don’t need your admin token. Anyone with the randomized download URL can grab the signed pass until the link expires (15 minutes by default). When delivering through Hark, Pocketful authenticates with a token for your Hark deployment and sends the pass description as the notification title, along with the download link.

Updatable passes bake in their own per-pass auth token and Wallet service URL. Apple Wallet uses that token to register the device for updates and fetch new builds. Pocketful stores the pass specs, tokens, and device registrations on disk in SQLite, while the actual .pkpass files and temporary download links stay in memory.

You configure your Apple Pass Type ID, Team ID, signing certificate, and private key once on the server. Every pass is signed with those credentials—an agent’s payload can’t spoof or swap in its own signing identity, and your private key never leaves the box. Apple Wallet checks the signed bundle when someone adds it.

While the agent supplies the text and images, Pocketful controls the lifecycle, keeping the full spec for updatable passes so it can issue new versions. Hark delivers the initial download link, and Apple Push Notification service (APNs) carries the update signal for passes already in your Wallet. When an update happens, Pocketful sends an empty push over APNs, prompting the iPhone’s Wallet app to wake up and pull the fresh bundle from your server.

We use revision-based cache IDs so Wallet won’t get confused even if you push two updates within the same second. Storing the underlying spec also means Pocketful can rebuild the .pkpass file on the fly whenever Wallet asks for it or whenever you need a fresh download link.

Pocketful catches missing icons and unreadable images before signing, and startup checks flag missing credentials or malformed certificate files right away. (One catch: if a valid cert simply doesn’t match your configured pass identity, the server may not know until Apple Wallet rejects the pass on the phone.)

If a Hark notification fails to send, Pocketful still keeps the signed pass ready and hands the download URL back to the caller along with the delivery error. Download links die when they expire, get evicted to make room in memory, or vanish with a server restart—though updatable passes can always spin up a new link from the spec stored in SQLite. Deleting a pass wipes its links and server registrations, though any copy already added to an iPhone stays in the user’s Wallet until they remove it.

When updating a pass, Pocketful commits the new version to the database before firing off APNs pushes, reporting both steps separately. If APNs fails or your push key is missing, the server can end up ahead of the phone; Wallet may refresh on its own schedule. Dead push tokens get pruned automatically.