Development environments

A development environment (dev env) is a copy of a production site that only agency admins can see. You change it first, check the changes on your local machine, and then push the ones you want to production. Changes stay in the development environment until you push them, so the live site is never edited by accident.

Each production site has at most one development environment, and every agency admin shares it. Clients never see it, its changes, or its push history.

Why it existsCopy Anchor Link

Without a development environment, every edit goes straight to the live site. When a client asks for a change, there is no safe place to try it. A development environment gives you that place. You can change content and schema in it, run the website on your machine against it, show the result to the client, and send only the approved changes to production.

The workflowCopy Anchor Link

1. Set up the site. Create the production site, add its collections, entries and languages, and go live. A new site is a normal site in Demo mode until then.
2. Create the development environment. Once the site is in Production mode or has gone live, open Settings › Development on the production site and select Create development environment.
3. Copy its tokens. The dialog shows the development site's tokens once. Copy them into your project's .env.local (see below).
4. Change it. Edit entries, sections and the schema in the CMS, with the CLI, or over MCP. Changes stay in the development environment.
5. Run it locally. With the development token in .env.local, mark the entries you want to check as ready and run areca pull. Code changes can be made at the same time. A development environment has no releases, so no go-live step is needed for the local check.
6. Review with the client. Share screenshots, collect small changes, and make them in the development environment or in code.
7. Push to production. Open the push screen, review the list, and push. Optionally start the production build in the same step.

When the client asks for something new later, reset the development environment from production first, so it starts from what is live.

Create, reset and deleteCopy Anchor Link

All three are in Settings › Development on the production site. Each is one click with a plain confirmation. No authenticator code is needed, because nothing is lost that is not already in production or on your machine.

• Create development environment. Copies the production schema (collections, sections and their fields, and the site languages) and the ready version of every entry. Entries that were never ready in production, and archived entries, are not copied. Media files are shared with production, so nothing is duplicated. The development site's name is the production name with "(dev)", and its slug is the production slug with -dev. If that slug is taken, the next free one is used, for example -dev-2.
• Reset from production. Throws away everything in the development environment and copies production again. Unpushed changes are lost and not archived. The dialog says how many. The tokens and the preview URL stay.
• Delete development environment. Removes it. Production is not changed. The same action is in the development site's Settings › General.

If production changed since the last reset or push, the development environment shows Production changed since the last sync with a count, and offers a reset.

Set up the local projectCopy Anchor Link

The development environment has its own site token. The website reads whichever token is in .env.local, so swapping that one value is how you choose what you are looking at.

For day-to-day work on the development environment, .env.local holds the development values:

ARECA_CMS_URL=https://cms.example.com
# The development environment's site token. Pulls read the development environment.
ARECA_SITE_TOKEN=<development-site-token>
# Code-first sites only: the development environment's schema token.
ARECA_SCHEMA_TOKEN=<development-schema-token>

Keep .env.local out of git, as usual.

Check the production site locallyCopy Anchor Link

To see what production will show, replace the values with the production site's values, pull, and check. The production tokens are the ones in your production deployment's environment. Areca shows a token only once, so if you no longer have it, rotate it in Settings › Developer on the production site and update the deployment with the new value. Rotating stops the old token working straight away.

1. Put the production site token in ARECA_SITE_TOKEN. For a code-first site, also put the production schema token in ARECA_SCHEMA_TOKEN.
2. Run areca pull and check the site.
3. Put the development values back, so you are working on the development environment again.

The siteKey in areca.config.ts is informational. The CMS uses the site that the token belongs to, so the token decides what you read.

Code-first sitesCopy Anchor Link

If the site syncs its content definitions from code with areca manifest push, read this before you push to production. A manifest push is a full sync. It replaces the production definitions with the file's, which can undo changes that were made in the CMS.

Before you send the manifest to production:

1. Keep the development values in .env.local, and run areca manifest pull. This updates areca.config.ts to match the development environment, so the file includes the changes made in the CMS.
2. Review the code changes you want, and commit them.
3. Push the schema to production through the push screen, or with areca manifest push using the production schema token once the file matches what you want live.

Code changes that are not in the file's content definitions (components, styles, pages) reach production with the next go live of the production site, as usual.

Pulls need no releaseCopy Anchor Link

An areca pull with the development token reads the development environment's ready content directly. It does not use a publication, so there is nothing to build or go live. Draft entries are not included, so mark an entry ready before you expect to see it locally.

A development token refuses a pinned publication. The --publication option, and the publicationId query, return an error for a development environment: "Development environments have no releases. Pull without a publication id."

Preview linksCopy Anchor Link

The development environment has its own Preview URL, in its Settings › General. It defaults to http://localhost:3000, so preview links from the development editor open your local site with your draft. Change it if your local site runs on another port.

The push screenCopy Anchor Link

Open Push to production from the banner at the top of the development environment. The screen is one list of everything that changed in the development environment since the last reset or push. Everything is ticked by default. Refresh reloads the list. The production site's Settings › Development tab shows the history of past pushes, resets and copies.

• Needs attention is at the top. These items are risky for production, so each one is set to Skip unless you switch it to Apply. Skip is the default, so an item you do not decide on is never pushed. The items are:
  • Changed in production since the last sync. Production and the development environment both changed the same item. Apply overwrites production with the development version.
  • Remove field, which drops content. The row says how many values will be archived.
  • Change of the main language. The row says how many entries it stamps.
  • Scheduled in production. Apply is not available until the schedule is resolved in production.
  • Deleted in production. Apply recreates the entry in production as a draft.
  • URL already used. Another production entry, or another entry in the same push, uses the same URL (the main slug, or a language's slug). Apply is not available. Change the URL in the development environment, then review the list again.
• The other groups are Schema, Languages, New entries, Changed and Archived. Untick anything you do not want to push.
• A removed field keeps the production values until you apply the removal. A row shows "Keeps 'excerpt' in production until the field removal is applied" when an entry depends on it.
• The button shows the count and the skipped items, for example "Push 12 changes · 2 skipped". Pushing needs no confirmation dialog. It asks only for a fresh authenticator code when your session is not fresh.
• Go live after push starts the production build once the push is saved. It is off by default. The browser remembers your last choice. It needs permission to go live.

If production or the development environment changed while you were reviewing, the list is refused with The plan changed. Your decisions stay for items that did not change. Items that did change are highlighted, with the note "The plan changed. Review the highlighted items again." Review them, then push again. Select Review again to reload the list.

Pushing never deletes content in production. An entry you removed in the development environment is archived in production. Drafts and ready versions are written; the live version changes only at the next production go live, unless you use Go live after push.

The result lists the counts, any warnings (for example, a ready version that could not be made ready in production, or references that were cleared), and links to the production entries. If nothing changed, it says "Nothing was pushed."

Copy one entry to productionCopy Anchor Link

To send only one entry or section, open it in the development environment and choose Copy to production as draft in the top bar menu. The copy becomes the draft of the matching production entry. The live version stays as it is, and the copy is not ready in production. Approving it is a separate step in the production CMS, or use markReady over MCP.

The copy is refused in three cases:

• The production schema for that collection does not match the development schema. The message says to push the schema first.
• Production changed since the last sync. The message then offers Overwrite, which replaces the production draft with your copy.
• The entry's URL is already used by another production entry, in the main language or in another language. Change the URL in development first. Overwrite does not change this.

Bulk actions on a normal siteCopy Anchor Link

On a site that is not a development environment, the collection list's bulk bar has an Archive action next to Mark as ready, Move to draft and Delete. Each entry is handled on its own, so one failure does not stop the rest, and the entries that could not be changed are listed.

AI apps and the agency connectorCopy Anchor Link

A development environment has its own connector, shown as site.devEnvironment.connectorUrl by get_site_info on the production connector. It is usually /api/mcp/<slug>-dev, but always use the URL the CMS gives you. Agency admins can connect an AI app to it, and the production connector reports the development environment to them.

The AI app can make the same changes as you can in the CMS. Its push is a review step: the first call is a dry run that lists every change and returns a plan. The push is refused unless the AI app gives back that plan, and the list needs your approval. Its Go live and scheduling tools are not offered on a development environment.

Agency admins can also use one agency connector for every client and site, instead of a connector per site. It is covered in Agency connector. Through it, pass the development environment's slug as site on each call.

See Connect AI and the MCP tools reference.

What a development environment does not doCopy Anchor Link

• It cannot go live, switch to Production mode, or be scheduled. It has no publications and no builds.
• Its preview links open your local site. The Preview URL is in its Settings › General, and defaults to http://localhost:3000.
• There is only one per production site. It is shared by all agency admins.
• It does not merge production changes into itself. Reset replaces it.
• Site settings such as the AI prompt, URLs and the deployment target are not pushed.
• Clients cannot see it, its changes, or its push history. Its activity is visible to agency admins only.