what is a production-shaped preview environment for ai agents?

A preview URL can answer a narrow question: what does this change look like?

That was enough when most proposed changes were reviewed one at a time by a developer who already understood the surrounding system. It is not enough when agents can change a frontend, API, worker, migration, route, and access rule in the same pull request. In a software factory, the harder question is no longer whether the page renders. It is whether the proposed system works.

That requires a different kind of preview.

most previews prove pixels, not systems

Suppose an agent adds durable progress tracking to an import feature. The change includes:

1. a frontend that starts an import and displays its progress;
2. an API that creates the job;
3. a worker that processes it;
4. a database migration that records progress and retry state;
5. a protected operations route for failed jobs.

A frontend preview can show the progress bar. It cannot prove that the API reaches the right worker, the migration applies, the worker writes the new state, or the operations route remains protected.

A coding sandbox goes further. It can give the agent an isolated filesystem, language runtimes, package installation, commands, and background processes. Cloudflare describes its Sandbox in those terms. That is useful execution infrastructure, but it still does not guarantee that the code is running through the application's real deployment topology, routing, policy, or managed services.

Shared staging can provide more realism, but it introduces another problem. If two agents deploy incompatible migrations or test the same queue at once, neither has a clean environment. A failure may belong to the proposed change, another branch, old staging data, or a manual edit. The environment is real, but the evidence is ambiguous. This is the deeper reason shared staging breaks under parallel agent work.

These are not bad tools. They answer narrower questions:

The last row needs a precise definition. Otherwise, “production-shaped” becomes another way to say “more realistic.”

same operational shape, separate mutable state

A production-shaped preview preserves the contracts that determine how the application behaves in production while withholding production's authority and mutable state.

It should preserve:

• service roles and relationships;
• routing and service discovery;
• access and edge policy;
• build, startup, migration, and health behavior;
• supported managed dependencies;
• runtime evidence and resource ownership.

It should not inherit:

• production database credentials;
• production traffic;
• unrestricted production integrations;
• shared mutable development state disguised as isolation;
• resources that survive after the preview has lost its owner.

The useful rule is short:

same operational shape, separate mutable state.

Shape is not scale. A preview may run one worker where production runs twenty. It may use a smaller database or a shorter retention window. The question is whether the roles, relationships, and policies needed to evaluate the change still exist.

1. the service topology has to survive the preview

Real applications are rarely one process. A web frontend may call an API, the API may enqueue work, a worker may consume it, a cron process may schedule cleanup, and a migration job may prepare the database before any of them become healthy.

If the preview drops one of those roles, it changes the system being tested. A frontend connected directly to a database is not a preview of a frontend that reaches the database through an API. An API with no worker cannot verify an asynchronous job. A worker started as an ad hoc command does not prove that the deployment platform understands it as a persistent service.

This does not require every service to be rebuilt for every small change. A platform can reuse an unchanged dependency when it can preserve isolation and prove which version is running. But that optimization must not silently reconnect the preview to shared mutable state.

The market is moving toward repository-defined, multi-service previews. Vercel Services can build multiple frontend and backend services together in one project and give the deployment one shared domain. Railway's PR environments can create an isolated temporary environment containing the relevant services from a base environment. Both reflect the underlying requirement: a full-stack change needs somewhere for the full stack to run.

2. routing is application behavior

Starting the right processes is not enough. Requests must reach them the intended way.

Consider a frontend at /, an API at /api, and an administrative service at /ops. The preview needs to preserve which service owns each path, how overlapping prefixes resolve, which services are public, and how internal calls remain inside the same preview.

A common false preview runs the new frontend at a unique URL but leaves its API base URL pointed at development. The page works until the proposed API contract diverges from development. Worse, the preview can write test data into a shared system while appearing isolated to the reviewer.

Routing is therefore part of the application's production shape, not incidental platform plumbing. Vercel's multi-service routing, for example, merges service routes into one table and evaluates path prefixes from most specific to least specific. That routing behavior is documented as part of the deployment model, because changing it changes the application.

A useful preview should be able to answer:

• Which service receives this request?
• Which preview does that service belong to?
• Where does an internal service name resolve?
• Can any route fall through to development or production?

If those answers are implicit, the preview is not a reliable verification boundary.

3. access policy belongs in the test

An application can behave correctly and still be unsafe because the preview removed the policy around it.

The intended preview should preserve the structure of controls such as:

• whether the application is public or protected;
• which routes require authentication;
• which services accept inbound traffic;
• which secrets and identities are scoped to the environment;
• which test credentials replace production credentials for external systems.

This does not mean copying production credentials into a preview. It means exercising the same policy structure with preview-safe identities and secrets.

Without that parity, a reviewer may verify an administrative route that is accidentally public, or conclude that an integration works only because the preview inherited a credential it should never possess. The policy is part of the proposed system, so it belongs in the evidence.

External side effects still need their own boundary. An isolated database cannot make a real payment, production email, or third-party deletion harmless. Those systems need sandbox credentials, fakes, or a human gate placed at the consequential action.

4. migrations have to run against preview-owned state

Schema changes expose the difference between a live page and a live system.

The preview should follow the real ordering contract: prepare the data source, run migrations, start the application, evaluate health, and only then declare the environment ready. The exact sequence varies by application, but it must not be replaced with an empty database that already happens to match the final schema.

For the import example, the preview needs to show that:

1. the migration creates the progress and retry fields;
2. the API can write them;
3. the worker can update them;
4. old and new processes do not disagree about the schema;
5. a failed migration prevents the environment from becoming healthy.

This still does not prove that the migration is safe against every historical production row. Risky data changes need production-shaped fixtures, compatibility analysis, or a separate migration rehearsal. The full agent migration test loop treats empty state, representative data, mixed-version compatibility, and destructive cleanup as separate claims. The preview proves a narrower and valuable claim: the proposed application can construct and run against its intended schema without touching a shared environment.

5. managed state needs ownership, not just a new url

Isolation must extend to the mutable services the platform manages.

A production-shaped preview should receive its own Postgres schema, database branch, or database; its own Redis database or namespace; and its own storage bucket or prefix. It may start empty, run a seed command, or copy an approved non-production source. What matters is that the resulting resource belongs to the preview and can be inspected, reset, and removed without targeting development or production.

Three rules follow:

1. Provisioning failure must block the preview. Falling back to development credentials turns an infrastructure error into silent data contamination.
2. The platform needs an ownership ledger. Teardown should identify the exact resources created for the preview rather than infer them from names.
3. Data hydration must be explicit. Empty, seeded, and cloned-from-development previews make different claims and should never be confused with a production data copy.

Render's preview environments provide a useful example of this boundary. They create new instances of the services and datastores declared in a Blueprint, but do not copy existing datastore contents by default. They also tie cleanup to the pull-request lifecycle or an expiry window. Render documents both behaviors.

“Production-shaped” should never be used as shorthand for “replica of production.” Production data brings privacy, security, and side-effect risks that topology alone does not. The safe default is the same operational structure with new state.

6. agents need a machine-readable lifecycle

A preview designed only for a human reviewer can stop at a URL and a green check. An agent needs enough structure to decide what to do next.

It should be able to determine:

• which branch and commit produced the preview;
• whether the deployment reached a terminal state;
• which service failed and where its logs live;
• which URLs and managed resources belong to the environment;
• whether development and production remained untouched;
• whether the preview can be reset safely;
• when it expires and whether teardown completed.

This turns the preview from a sharing feature into a verification interface.

The agent still owns the product-specific test. It must call the import endpoint, watch the worker, inspect the progress record, and test the retry path. The deployment platform's job is to provide a faithful environment and enough structured evidence for those checks to run without scraping a dashboard or guessing from elapsed time.

a practical evaluation test

Give a platform one change that crosses a web service, an API, a worker, Postgres, and a protected operations route. Then ask:

1. Does the preview create or resolve every service role required by the change?
2. Does the frontend call the API belonging to the same preview?
3. Does the worker connect only to preview-owned state?
4. Do migrations run through the real deployment lifecycle?
5. Does the protected route retain its access boundary?
6. Can an agent inspect service-specific state and logs through structured interfaces?
7. Can managed state be reset without affecting development or production?
8. Does closing the pull request remove everything the preview owns?

Run the test through failure paths. Break the build. Fail a migration. Make a health check time out. Attempt to provision an unavailable managed dependency. A production-shaped preview should fail closed and return evidence that identifies the broken contract.

If the platform cannot answer these questions, it may provide a useful preview URL. It does not yet provide a production-shaped preview environment.

where floo fits

floo treats a preview as an environment belonging to one branch, not merely another deployment URL.

The repository describes the application's auditable service, routing, access, migration, and managed-service shape. A branch can become an isolated preview environment that runs through the normal deployment pipeline. Multi-service previews use the same gateway routing semantics as permanent environments, with concrete service URLs for inspection.

For floo-managed Postgres, Redis, and storage, the preview receives preview-owned resources and credentials. If floo cannot provision that isolation, it blocks the preview rather than reconnecting the application to development state. Preview data starts empty by default. Teams can seed it or clone supported managed data from development, but floo does not copy production data into a preview.

The lifecycle is visible to agents. Structured output ties the source branch and deploy to its URLs, expiry, and managed-resource branches, and explicitly reports that development and production remained untouched. The same ownership record supports targeted reset and teardown when the pull request closes or the preview expires.

That is the useful boundary. The environment is real enough for an agent to learn from, but isolated enough to create, inspect, break, reset, and remove as part of the normal development loop.

Code generation makes proposed changes cheap. Verification becomes the scarce part of the system. A production-shaped preview gives each change somewhere real to run without giving it somewhere consequential to fail.

That requires more than a screenshot and more than a shell. It requires the application's topology, routing, policy, migrations, and managed dependencies to exist together inside one isolated lifecycle. This is the preview model floo is built around.