Duplicating a Project

Duplicate a project to get a new project that is shaped like it: the same data model, access rules, settings, automation, microapps and app code, with no data. Use it to start a staging copy, a new customer’s project or a template.

The copy is a new Buildpad Engine project in the same organization. It gets its own addresses, credentials and tokens. The project you duplicate is not changed.

If the More actions (⋯) menu of the project’s Details page has no Duplicate project, you cannot duplicate this project. See Who Can Duplicate.

Who Can Duplicate

You can duplicate a project when you can create projects in the organization and update this project (or you created it). The copy carries the project’s rules and automation code, so a member who cannot change the project cannot take its structure.

Duplicating

Open the project’s Details page.
Open More actions (⋯) next to the project’s name, and click Duplicate project.
Type the name of the copy. The proposal is “Copy of” and the project’s name. The name must not be used by another project in the organization.
Click Duplicate. The browser opens the copy’s Details page.

The platform refuses the duplicate, and says why, when:

the organization has reached its limit of projects, or the copy’s microapps would pass its limit of microapps;
the project is not running yet, or an operation holds it: a creation, a deletion, a version update, a backup or a restore, or a move to the Buildpad Engine.

A Supabase project whose administrator has two-factor sign-in asks for a static token of an administrator. The platform uses the token for this copy only, and deletes it when the structure is copied.

Following the Copy

The copy’s Details page shows Duplicated from and the name of the project, with the steps:

Creating the project: the copy is created as any new project.
Copying the structure: the data model, the access rules, the settings and the automation.
Creating the microapps: one microapp for each microapp of the project, with the same name and type.
Copying the code: the code of the main app and of each microapp.

The page updates by itself. If a step fails, the page shows the reason and Retry. Retry starts the step again. It does not copy again what is already copied.

If a microapp of the copy is not created, delete that microapp in the copy, then click Retry.

When the copy is done, the page shows the report. Click Dismiss to hide it.

What Is Copied

Copied	Not copied
Collections, fields and relations	Users
Roles, policies and permission rules	Records of any collection
Scope types and the collections’ scope settings	Files and folders
Settings	Scope items (each one is a tenant, which is data)
Hooks, cron jobs, services and workflows, switched off	The email (SMTP) password
Each microapp	Workers, connectors and mobile app builds
The code of each app: its `main` branch, with its history	Project members, MCP tokens, backups, monitoring settings and usage
	Other branches and tags of the code

The copy gets the connectors that any new project gets. It is created on the platform’s current data service version.

The Buildpad Engine needs a primary key on every table. A table without one gets its id column as its key in the copy, and the report says so. A table with no key and no id column stops the copy: add a key to it in the project, then click Retry. A column that points to a scope item by its ID, not its URI, is copied without that link, because the Buildpad Engine links scope items by URI only; the report lists it under the items the copy refused.

A permission rule that names a scope item is not copied, because the copy has no scope items. The report lists each rule or setting that the copy refused, with the reason.

The Code

The code of each app is copied into the copy’s own repository, as the branch main, with its history. One commit, Point the code at the copy, points the code at the copy:

every text file that names the project’s id, a microapp’s id, the tenant id or an app hosting id names the copy’s instead. This covers the Engine URL, a mobile app’s API address and the ids in the agent instructions;
the environment files and .buildpad/project.json name the copy’s Engine URL and tenant id. Files such as .env.example keep their placeholders.

Binary files are not changed. The copy’s app hosting has the copy’s own settings, as for any new project, and builds the copied code.

An app with no code in the project gets no code in the copy. The report says so.

After the Copy

Do these steps in the copy. The report lists the steps that apply:

Set the email (SMTP) password in the Studio.
Switch on the hooks, cron jobs and services that you need. The report lists each one. A copied cron job that writes to an outside system runs once for each project when it is on, so check it first.
Add users and give them roles.
For a Supabase project, review and merge the port branch (see below).

Duplicating a Supabase Project

The copy is always a Buildpad Engine project. For a Supabase project:

The structure is read from the project and written to the copy, as a move to the Buildpad Engine copies it, without the users, the records and the files.
The code is copied to main as it is, with the environment pointed at the copy. Supabase code does not work on the Buildpad Engine, so the copy’s apps do not work until you port the code.
Each app also gets a branch move-to-engine in the copy’s repository: the port that Fix_App can do, with MOVE-TO-ENGINE.md, the list of the places to port by hand. Review the branch, finish the port, and merge it into main. See Moving to the Buildpad Engine.