Upgrading from Explore to a paid plan

This is the page an upgrade_required (or any entitlement-gated) tool result points you at. You, the agent, hit a capability that the user's current plan doesn't include. This page tells you exactly what the free tier contains, what a card unlocks, and the precise next step. You never handle the card. Your job is to explain what unlocks and hand the human the upgrade link.

How to present this to the user (do this, in order)

1. Say what they hit. Name the specific capability the gate refused (e.g. "custom domains", "the REST API", "object storage", "editing the Dockerfile / build recipe"). The gate's error message and code tell you which one.
2. Say what unlocks. Adding a card flips on the whole set below at once, not just the one thing they hit. Mention that, because it usually changes the calculus.
3. Give them the link. If the gate payload included an upgradeUrl, hand the human that link and tell them to add a card there. If there's no upgradeUrl (billing not wired in this deployment), tell them upgrading isn't self-serve here yet and they should contact the operator. Do not invent a URL.
4. Stop. Do not ask for card details. Do not try to enter payment information. The card hand-off is the human's, in their browser, the same way secrets never reach you.

The plans

What free Explore contains (and its limits)

Explore is deliberately contained: a place to see your agent rebuild an app, not a tier for production. On Explore you get:

• 1 app, from a curated template only (no arbitrary import of an existing repo).
• A 150 GB-hour/month awake-compute pool, on top of a fixed 30-minute idle window it can't tune. Free is pool-governed like every paid tier — it just gets a small pool, and exhausting it sleeps apps rather than billing anything.
• No persistent storage. App state must live in the managed database, not on a volume.
• Free, unlimited seats — seats are never a paid lever on any plan, free included.
• The MCP endpoint (POST /mcp) and app-source edits stay open, so the user can keep watching their agent change the app and redeploy. The deploy loop over MCP is never trapped behind a paywall.

What Explore does not include (each of these is its own upgrade_required gate):

• Custom domains. Explore apps are subdomain-only.
• The REST API (/api/v1) and API keys, the headless/automation surface. (Drive the app with your agent over MCP instead while on free.)
• Object storage (managed S3/R2 buckets).
• Open egress. Outbound network is locked down on free.
• Editing the build recipe. The Dockerfile / build config is locked on free (you may still edit app source and redeploy).
• Custom templates and arbitrary import of an existing repo.
• Always-on apps. Explore apps are forced to sleep on their fixed 30-minute idle window.
• Custom CPU / memory sizing (set_app_resources). On free, compute size is platform-managed.
• Read-row SQL (query_database). Schema inspection with describe_database stays free.
• Restore to a new database and swap_database. In-place restore_backup stays free.
• Scheduled backup verification, the automated daily restore drill. On-demand verify_backup stays free.
• Outbound webhooks to the user's own endpoints.
• Dropping the "Built on deploymill" badge that free scaffolds ship with.

Plus conservative build rate caps.

What a card lifts on, all at once

The moment the user adds a card (the $19/mo Builder base, the $79/mo Studio base, or any paid add-on), the entire contained envelope flips on together. There is no à-la-carte "just custom domains" toggle on the base. One card unlocks all of:

• Custom domains (attach a domain the user owns, with TLS).
• The REST API (/api/v1) + org API keys (programmatic/headless access for scripts and CI).
• Object storage (managed buckets).
• Open egress (unlocked outbound networking).
• An editable build recipe (the agent may edit the Dockerfile / build config).
• Custom templates (scaffold from the workspace's own templates repo).
• Arbitrary import of an existing repo (import_repo on a repo the platform didn't scaffold).
• Always-on apps (pin an app awake instead of letting it sleep, drawing the pool continuously).
• Custom CPU / memory sizing (set_app_resources).
• Read-row SQL (query_database; describe_database is free on every plan).
• Restore to a new database and swap_database (in-place restore_backup is free on every plan).
• Scheduled backup verification, the automated daily restore drill (on-demand verify_backup is free on every plan).
• Outbound webhooks to the user's own endpoints.
• Dropping the "Built on deploymill" badge from new scaffolds.

(SSO and priority support are the exceptions: they're Enterprise-only and are not unlocked by simply adding a card. The pool isn't on this list either, because it isn't a switch that flips. It's the plan's own included capacity, so a card grants Builder's 2,000 GB-hours or Studio's 10,000, never an unbounded pool.)

So when a user balks at upgrading for the one thing they hit, remind them they're unlocking the whole set, not paying $19 for a single feature. The $19/mo is flat and never grows into a surprise bill — it includes a 2,000 GB-hour/month pool of awake compute, which covers about five always-on 512 MB apps, or many more apps that mostly sleep.

The exact next step

• If the gate gave you an upgradeUrl: tell the user to open it and add a card. That's the entire action: once the card is on file the gate clears and you can retry the refused tool call.
• If there's no upgradeUrl: billing isn't self-serve in this deployment. Tell the user upgrading requires the operator, and surface whatever support/contact path the deployment documents. Don't fabricate a link.

After the user confirms they've added a card, retry the original tool call. The entitlement resolver picks up the new state, and the capability that was gated will now succeed.

If you hit pool_exhausted instead

pool_exhausted is a different gate from upgrade_required. It means the org's included GB-hours (150/mo on Explore, 2,000 on Builder, 10,000 on Studio) are used up for the current billing period. Every tier is pool-governed, so a free workspace can hit this too. This is never a billing event. Nothing is charged past the flat monthly price (and on Explore there's no card to charge at all). The workspace just stops being able to start new work. Moving up a tier is the self-serve fix, and an operator can also raise the pool.

• New app creation and waking a sleeping/preview app are refused with pool_exhausted until the pool has headroom again.
• A running production app is not immediately stopped. It keeps serving past 100% of the pool (the org's admins are notified), and only sleeps if usage reaches the hard ceiling (125% of the pool).
• The pool resets on the 1st of the calendar month (UTC), or an operator can raise the org's pool via an admin override — tell the user this isn't a self-serve slider; if they need more headroom before the reset, they should contact the operator (or whatever support path the deployment documents). Sleeping some idle apps or previews is usually the fastest way to free up pool before the reset.
• Don't confuse this with upgrade_required. Every tier is pool-governed, free included (Explore gets 150 GB-hours), so a free org CAN see pool_exhausted — it means "out of capacity this month", not "this feature needs a card". The fix differs too: upgrade_required needs a card, while pool_exhausted is solved by sleeping idle apps, waiting for the 1st, or moving up a tier.