> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newly.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Production and secrets

> Deploy your Newly Backend to production with the newly CLI, and keep API keys out of your app.

In Newly (app.newly.app), your [Newly Backend](https://docs.newly.app/backend/overview.md) 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**.

**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](https://docs.newly.app/code/where-your-code-lives.md#branches-dev-and-main).

**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:

| Settings says | What it means |
| - | - |
| "Production is up to date with main (abc1234)." | Production runs the latest `main`. There's nothing to deploy. |
| "main has new commits that are not on production." | `main` moved since the last deploy. Deploy to catch production up. |
| "No production backend yet." | You haven't deployed to production. The first deploy sets it up. |
| "main has no backend to deploy yet." | Your backend isn't on `main`, so there's nothing to deploy and no button. If it's on `dev`, update main first. |

### 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](#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](#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.

```bash theme={null}
npm i -g @newly/cli
newly login --email
newly pull <project-id>
newly deploy --env prod
```

Your project id is the last part of the web app address: `app.newly.app/projects/<id>`.

> [!WARNING]
>
> `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](https://docs.newly.app/backend/database-backups.md) 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**. 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 Google and Apple sign-in keys. Password reset and verification emails need no key: see [Sign-in for your app](https://docs.newly.app/backend/app-sign-in.md#emails-for-password-reset-and-verification). 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:

```bash theme={null}
newly secrets set KEY VALUE --service api
newly deploy --env dev
```

* 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](https://docs.newly.app/backend/app-sign-in.md).
* **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`:

```bash theme={null}
newly secrets set KEY VALUE --service api --env prod
newly deploy --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.

## Database access and logs

| Command | What it does |
| - | - |
| `newly db url` | Print a read-only address for your dev database |
| `newly db url --env prod --role owner` | Export the production database owner's connection URL; project owner only |
| `newly logs` | Show recent logs from your dev backend |

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](https://docs.newly.app/backend/database-backups.md#backups-that-can-run-while-newly-is-unavailable).

## 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](https://docs.newly.app/billing/out-of-credits.md).

## Related

> [card] [Get your code](https://docs.newly.app/code/get-your-code.md)
>
> Install the newly CLI and download your project.

> [card] [AI features in your app](https://docs.newly.app/backend/ai-models)
>
> Let your app use AI models, and what that costs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.