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

# Deploy an application

> Build a folder or Git repository, check readiness, and update an existing application.

Start with a working [Engine installation](/engine/installation). For a complete sample application, follow the [quickstart](/engine/quickstart).

## Prepare the application

Nerdit supports a supplied `Dockerfile`, Python projects with `requirements.txt` or `pyproject.toml`, and Node projects with `package.json`. A Dockerfile takes precedence. Node uses `npm ci` when a lockfile is present and `npm install` otherwise; provide a `start` script or explicit start command. For Python, set the actual command instead of relying on the default `uvicorn main:app` fallback.

```toml nerdit.toml theme={null}
[deploy]
name = "my-app"
port = 8000
gpus = 0
start = "uvicorn main:app --host 0.0.0.0 --port 8000"
health = "/health"
```

This example requires your application to provide `main:app`, install Uvicorn, and implement `/health`. Bind to `0.0.0.0` inside the container. Use a stable DNS-label application name.

<Warning>
  Containers drop Linux capabilities and use `no-new-privileges` by default. Images whose entrypoint needs `chown`, privilege changes, or privileged ports may fail. Build an image that works under these restrictions; do not disable the sandbox to make a stock image's startup script work.
</Warning>

## Preview and deploy

```bash theme={null}
nerdit deploy ./my-app --dry-run
nerdit deploy ./my-app --wait
nerdit services list
```

The dry-run validates configuration and shows planned changes without starting a build. Deployment uploads the folder, builds on the Engine, and starts a supervised service. Keep secrets out of the folder; upload exclusions are not a substitute for reviewing its contents.

`--wait` exits `0` when the requested generation converges, `1` for failure or supersession, and `3` on timeout. A timeout alone does not mean the build failed:

```bash theme={null}
nerdit services wait my-app --timeout 300
nerdit diagnose my-app
```

Open the URL reported by the service. With the proxy disabled, that is a loopback address on the **Engine machine**. [Enable HTTPS](/engine/networking) for routed URLs. Read the current endpoint after updates; health-gated cutover can change its effective host port.

## Deploy from Git or the store

Git runs on the Engine machine and must be installed there. Use an HTTPS repository on a host permitted by the Engine's Git allowlist:

```bash theme={null}
nerdit deploy --repo https://github.com/YOUR-ORG/YOUR-APP.git --ref main --dry-run
nerdit deploy --repo https://github.com/YOUR-ORG/YOUR-APP.git --ref main --wait
```

Replace the repository and branch with your own. Use `--subdir` when the deployable application lives in a subdirectory. For a private repository, pass a secret reference with `--token-ref`, never a credential embedded in the Git URL. Linked GitHub App deployment is an account integration; follow the [App](/app/) flow for its repository access.

```bash theme={null}
nerdit store list
nerdit store show TEMPLATE_ID
nerdit store deploy TEMPLATE_ID --name my-app
nerdit services wait my-app --timeout 300
```

Choose `TEMPLATE_ID` from the returned catalog and inspect its prerequisites before deploying it.

## Update or roll back

For a folder deployment, repeat the folder command. For an application whose source is recorded as Git:

```bash theme={null}
nerdit services redeploy my-app --dry-run
nerdit services redeploy my-app --wait
```

Folder and agent-workspace applications cannot use this Git-only redeploy operation. Upload the folder again or use the [MCP workspace workflow](/engine/mcp).

Roll back a folder application's image to the retained previous version:

```bash theme={null}
nerdit deploy ./my-app --rollback --wait
```

Nerdit retains recent image versions. A rollback does not restore application data or undo a database migration.

## Understand cutover and migrations

When the proxy is available and the application uses no GPUs, eligible redeploys start a candidate container alongside the previous version and switch routing after readiness. A failed candidate leaves the previous version serving. Proxy-disabled, GPU, model, and database workloads do not use that same cutover path.

Both application generations can touch the same persistent volumes during cutover. Make writes and schema changes compatible with that overlap. Set `cutover = false` under `[deploy]` if the application cannot tolerate it.

An optional release command runs before promotion:

```toml theme={null}
[deploy]
release = "alembic upgrade head"
```

The image must contain the migration tool. Release commands run through a shell with the application's environment and volumes. A nonzero exit blocks deployment, but changes already made to the database are not automatically undone. Design migrations to be repeatable, back up first, and investigate an interrupted migration before retrying. Removing the TOML line alone may retain the stored release command; clear it through [configuration](/engine/configuration).

Continue with [service operations](/engine/operations), [models](/engine/ai), and [databases](/engine/databases).