Skip to main content
In Newly, at app.newly.app and in Newly for Mac, your Newly Backend has a dev environment and a production environment. The agent builds and tests on dev. Moving your backend to production is a step you take yourself.

​
Why the agent can’t deploy to production

The agent in your chats works on your dev backend. It can’t deploy to production, change production secrets or read production logs. If it tries, it gets “Managed Newly agent sessions can operate only on the dev backend”. This keeps your live app safe from changes made while you’re still building. Deploying to production is a button you press yourself. You need to be the project’s owner or have Admin access to it.

​
Deploy your backend to production

Production always runs your main branch. Deploying takes two steps in Settings then Project, in the web app or the Mac app. Production backend and Backend secrets show there once your project has a backend. If your app doesn’t have one yet, ask the agent to add it first.
1

Update main from dev

If your chats made changes that aren’t on main yet, Settings says so under Update main, for example “dev has 3 changes that are not on main yet.” Select Update main from dev, then Update main.This copies everything on dev onto main. Production doesn’t change yet. If dev and main changed the same code in different ways, nothing is copied and Settings lists the files. Ask the agent to resolve them in a chat, then try again. See Branches.
2

Deploy backend to prod

Under Production backend, select Deploy backend to prod, then Deploy to production.Newly builds the backend on main and deploys it. This usually takes a few minutes, and you can leave the page while it runs. If your project doesn’t have a production backend yet, Newly sets one up first.
Production backend always tells you where production stands:

​
Database migrations

A deploy runs the database migrations on main against your production database, in order. If a migration fails, the deploy stops and production stays on its previous version. If a migration on a branch was created before one that’s already on production, the deploy refuses to skip it and says so. Ask the agent to regenerate that migration, update main, and deploy again.

​
If a deploy fails

Settings shows why, with the last lines of the build log. Production stays on its previous version. Common reasons:
  • A production secret is missing. Add it in Backend secrets with the switch on prod, then deploy again. See Production secrets.
  • The backend on main did not build. The log lines name the file and the error. Ask the agent to fix it, update main, and deploy again.
  • A database migration failed. See Database migrations.

​
Deploy from the newly CLI instead

You can still deploy from a terminal, for example from a script. You need Node 20 or later.
Your project id is the last part of the web app address: app.newly.app/projects/<id>.
newly deploy ships the backend/ folder on your computer, not main. newly pull downloads dev, so a CLI deploy can put code on production that isn’t on main. The Deploy backend to prod button always deploys main.

​
Database snapshots before deployment

Deploying doesn’t automatically create a database snapshot. The project owner can create one explicitly with newly db backup create --env prod, or invoke that manual command from their own scheduler. Snapshot creation doesn’t apply migrations or verify that a database change is safe. See Database backups for commands, retention limits, automation credentials and a GitHub Actions example.

​
Secrets and API keys

A secret is a private value your backend needs, such as a payment provider key or a Google sign-in client secret.

​
Don’t paste secrets into a chat

The agent won’t take a secret pasted into a chat. Set it yourself, in Settings or with the newly CLI. Both write the same secrets, for the same environments.

​
Set a secret in Settings

With the project open, go to Settings then Project, and find Backend secrets. It works in the web app and in the Mac app, and you need to be the project’s owner or have Admin access. It shows once your project has a backend.
1

Pick the environment

Switch between dev and prod at the top of the row. Each environment keeps its own secrets.If that environment has no backend yet, the row says so and offers Provision dev backend (or prod). Provisioning creates its database and Worker, and usually takes about a minute. The server code itself still comes from the agent.
2

Pick the service

Switch between API and Sign-in. API holds keys your app’s server code reads. Sign-in holds keys your sign-in service reads, such as an email provider key for password-reset emails, or Google and Apple sign-in keys. A key saved under the other one never reaches the code that reads it.
3

Add the secret

Type the name, such as WEATHER_API_KEY, and the value, then press Add. The secret then shows in the list.
4

Change or remove one later

Saved secrets are listed by name, with only the first two characters of the value and its length. Values never come back out, of the panel or of the API, so replace a secret by typing a new value over it. Remove deletes it.
Keys Newly manages for you, such as your database connection, aren’t editable here: “<KEY> is managed by Newly and cannot be changed here.” A secret takes effect on the next deploy of that environment.

​
Set a dev secret with the CLI

From a freshly pulled project folder, run:
  • Use --service api for keys your app’s own server code uses.
  • Use --service auth for sign-in keys, such as GOOGLE_CLIENT_ID. See Sign-in for your app.
  • Always pass --service api or --service auth. The default doesn’t work, and the command fails with “service must be api or auth”.
  • A secret takes effect on the next deploy. newly deploy --env dev also deploys your local backend/ folder, so pull the latest code first.
To see which secrets are set, run newly secrets list --service api (or --service auth).

​
Production secrets

Set them in Settings then Project then Backend secrets with the switch on prod, or from the CLI with the same command plus --env prod:
You need to be the project’s owner or have Admin access, the same as deploying to production. The agent can’t read or change production secrets. To see which production secrets are set, run newly secrets list --service api --env prod (or --service auth).

​
Public settings in your app

Some values aren’t secret, such as your backend’s public address. These go in your app’s app.json under expo.extra. Never put a secret inside your app. Anyone can extract values from an app they’ve downloaded. Keep secrets on your backend and let your backend call the other service.

​
The Credentials panel is not for app keys

In the Mac app, Settings then Credentials holds keys for the agent and its tools, such as your Claude, OpenAI or Expo credentials. It doesn’t send keys to your app or your backend, even if the agent points you there. Your app’s own keys go in Backend secrets above, or in newly secrets set.

​
Database access and logs

An owner connection URL contains a password and allows direct database access. Save it securely before an outage if you need to connect without Newly. See Database backups.

​
Creating a backend-only project needs credits

newly create makes a new backend-only project from the command line. It needs a positive credit balance. With no credits, it shows “You do not have any credits left.” Add credits and try again. See Running out of credits.

Get your code

Install the newly CLI and download your project.

AI features in your app

Let your app use AI models, and what that costs.