Hand an app to another account #

View this page as Markdown

On this page

Prompt:

I've built this app for a client. Help me hand over the code and data so they can run it in their own account.

Create a new application in the receiving account, deploy the source there, and load the data you exported from the giving account. Use this for finished work with no live end users, including work you move between two accounts of your own.

You cannot hand over an application with live end users this way. The export contains no user accounts, sessions, or passkeys. Keep that application in its current account; the owners must choose another arrangement before proceeding.

Before your AI starts #

For each owner's AI tool: Check these inputs with the owner you act for.

  • Connect and sign in to the correct account (Connect your AI assistant). Use read_account to check it. Each owner uses their own sign-in and credentials.
  • Identify the source repository, manifest, application identifier, and environments that hold data. list_applications and read_status show the application's environments.
  • Read the application's database migrations, storage areas, upstream declarations, secret names, sign-in settings and push configuration. The giving owner's export_account supplies the recorded settings (Export).
  • Confirm there are no live end users. Ask the giving owner before stopping writes or changing a domain. The receiving owner needs the source code and access to any outside service the app calls.
  • Agree when the receiver will confirm the new app works, and when the giver may stop the old one. Both applications can incur usage while they run.

Steps #

1. Giver: prepare the source and settings #

Give the receiver the source repository through your usual private sharing method. Include the manifest, migrations, build instructions, and the dependency files needed to reproduce the app. The platform's built image cannot be downloaded. A deploy ZIP you kept in your own storage area remains a stored file and can be included in the data export.

Have your AI tool call export_account and save the answer. This export covers the whole account. Share only the selected application's settings, or share its manifest from the source repository; leave other applications' and account records out of the handover.

List the secret names the receiver must supply. Secret values are never exported. The receiver should obtain new provider keys where possible. Supply a value directly to the receiver only where you intend to share that credential; keep it out of source, chat, and the settings export.

2. Giver: export each environment's data #

Have your AI tool follow Export each application's data. Call tzcloud_request_export for the selected application and environment. Keep the returned export identifier, and call tzcloud_read_export until its state is completed.

Call tzcloud_request_export again with download: true and that identifier, then run the returned download command. Save the download outside the application's source folder and outside Git. Export development separately if it holds data you need.

Give the receiver the downloaded export and its manifest.json through a private file transfer. The manifest lists the tables, their columns and row counts, and the stored files with their sizes and versions.

The database tables are consistent at database.read_at. Stored files are listed at export time and downloaded afterward; a file that changed can arrive at a later version. Read the download's result for missing or changed files.

Before the final export, stop writes through the application's own controls, at the giver's agreed time. Keep them stopped until the receiver checks the final copy. If files keep changing, repeat the export and download after writes have stopped. Keep a completed download before starting another export, which removes earlier export folders on the platform.

3. Receiver: create and deploy the new application #

Under the receiving account's own sign-in, follow Deploy from your computer. Create a new application and submit its manifest. Enable development as Test in development, then promote describes, then deploy the handed-over source there.

Use the new application's identifier and settings. Check the code for old application identifiers and addresses before deploying. The old version history, logs and usage records stay with the giver's application.

Declare the needed database, storage areas, and upstreams for the new application. Store the receiver's secret values again using Keep a secret value out of chat. The new application's platform credential is supplied by its deployment; do not copy the giver's.

Apply sign-in settings from the handed-over configuration using Configure the realm. A field set by the manifest's realm member stays in the manifest. Reconfigure push with configure_push and the receiver's provider credentials if the app uses it (Send push notifications).

4. Receiver: load the data and files #

The export is a set of CSV files and stored files. There is no platform command that imports them into another application's production database. query_database runs read-only statements, and the production database's connection string is never shown to you.

For an app with database data, ask your AI tool:

Add a one-time loader for this app's exported tables. Test it in development, preserve the rows and their relationships, and make retries safe before running it in production.

The receiver's AI tool writes that loader as part of the application, using its database package and schema. It can read the CSV files from a private storage area and write through the application's own database connection. Add a database explains the connection and startup migrations.

Have the AI tool check column types, empty and null values, keys, relationships, and generated sequences against the source schema. Keep migration bookkeeping separate from the application data it loads. Test those cases in development. Keep a persistent completion record or another way to prevent a retry from inserting the same data twice.

Run the loader through a controlled server-side step, such as a migration before the server starts. Give it no public import route. After loading, have it stop safely on later starts, and remove the temporary input files when the receiver has checked the result.

For stored files, follow An upload grant from your tool. Under the receiver's sign-in, call mint_upload_grant for each destination file and run its returned upload command. Name the destination environment on every upload: development for testing, production for the final copy. Preserve the application's expected area names and paths, updating references where they changed.

Check the new tables' row counts against manifest.json with read-only queries. Compare representative values and relationships, then check the uploaded files' sizes and contents. Investigate every mismatch before directing users to the new app.

Promote only after development and the loader checks pass (Test in development, then promote). Load and check the final production copy using the same tested code. Promoting code does not copy development's database rows into production.

5. Both owners: move the address, if needed #

First check the receiver's app at its new platform address. If it needs the giver's custom domain, follow Change or remove the domain, then the attachment steps on that page.

The giver detaches the name first, after approving the interruption. Only then can the receiver attach it to the new application and add the DNS records that the platform returns. Detaching stops passkeys for that domain; this procedure requires an app with no live end users.

A custom domain is charged by the calendar month, with nothing returned on detach. Attaching it to the receiving account can incur a charge there in the same month. Read the current rate on the pricing page; agree on that cost before moving it.

The domain move can interrupt access. If it fails, keep both applications and the exports. The owners choose whether to retry the receiver's attachment or reattach the name to the giver's app. Check read_status until the chosen attachment is serving.

6. Receiver: confirm; giver: finish #

The receiver checks the new production app: its main routes, data, uploaded files, outside-service calls, sign-in settings, and domain where used. Keep the exports until the receiver confirms the copy is complete.

Issue-space bindings and their records do not travel with this copy. If the new app declares issue_tracking, it gets its own space (Feedback in your application's space). Read or export any old issue records you need before deleting the original application; the linked section gives both routes. A tzMesh participant is separate too; use the receiving account's own messaging identity.

The giver's application keeps running and incurring its own usage until the giver stops or deletes it. After the receiver confirms success, ask the giver whether to delete the old application. Follow Delete the application and its approval, keeping the verified export first. Deletion removes that application's data.

Expected result #

The receiver has a separately created application under their own account, running the handed-over source and the verified data copy. Each account pays for its own usage. The giver retains the original app until they approve its removal.

Refusals #

What you see Cause Remedy
The app has live end users The export contains no user accounts, sessions or passkeys. Stop before changing either application. This procedure cannot hand over those users.
The source code is missing The platform's built image cannot replace the source repository. Ask the giver for the source repository.
An export fails or a download reports missing or changed files The export did not complete, or files changed or became unavailable during the download. Keep the old application and the copies you have. Follow the export guide's recovery, stop writes at the agreed time, and repeat the final export.
query_not_read_only while loading rows query_database accepts only read-only statements. Use the receiver's application code for writes. Do not try to make query_database accept an import.
Rows or files do not match The loaded copy differs from the export. Stop before changing the address or deleting anything. Have the receiver's AI tool correct and retest the loader or upload, then repeat the comparison.
A secret is missing Secret values are never exported. The receiver stores a new value or obtains the intended value directly from the giver. Exporting again returns no secret value.
custom_domain_invalid because the other app holds the name The domain is still attached to the giver's application. Have the giver detach it first, with approval, then retry the receiver's declaration.
Creation or deployment is refused The named refusal identifies the account limit, balance or other cause. Read that refusal in the deploy guide and resolve it under the receiver's account. Leave the giver's app running.