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

# App settings

> Configure build, runtime, and advanced settings for an app. Settings are scoped per environment and take effect on the next deployment.

<Info>
  Unkey Deploy is in public beta. To try it, open the product switcher in the
  top-left of the dashboard and select **Deploy**. During beta, deployed
  resources are free. We're eager for feedback, so let us know what you think
  on [Discord](https://unkey.com/discord), [X](https://x.com/unkeydev), or
  email [support@unkey.com](mailto:support@unkey.com).
</Info>

App settings control how Unkey builds and runs your service. Each [app](/platform/apps/overview) has its own settings, and most settings are scoped per environment so production and preview can differ. You can configure these during project creation or update them from the **Settings** tab in your project dashboard.

<Note>
  Most settings take effect on the next deployment. After saving changes, trigger a new deployment to apply them.
</Note>

## Build settings

Build settings determine how Unkey turns your source code into a container image.

### GitHub repository

Connect a GitHub repository to trigger automatic deployments on push events. Pushes to the default branch deploy to production, and pushes to other branches deploy to preview environments. See [GitHub integration](/build-and-deploy/github) for details.

### Root directory

The build context directory where `COPY` and `ADD` commands in your Dockerfile are relative to. Defaults to the repository root (`.`).

Set this when your Dockerfile lives in a subdirectory, for example `services/api`.

### Dockerfile

The path to the Dockerfile used for building your application. Unkey auto-detects Dockerfiles in your build context. If your Dockerfile has a non-standard name or location, select it from the dropdown or enter a custom path.

Defaults to `Dockerfile` in the root directory.

### Watch paths

Glob patterns that control which file changes trigger a deployment. When configured, Unkey skips deployments if none of the changed files match any pattern.

Leave empty to deploy on all changes. Examples:

* `src/**` deploys only when files in the `src` directory change
* `**/*.go` deploys only when Go files change

You can add multiple patterns. A deployment triggers if any pattern matches a changed file.

### Auto deploy

Controls whether GitHub pushes automatically trigger deployments. Configured per environment so you can deploy production manually while letting preview branches deploy on every push (or vice versa).

| Toggle     | Behavior when enabled (default)                                              |
| ---------- | ---------------------------------------------------------------------------- |
| Production | Pushes to the default branch deploy to production automatically              |
| Preview    | Pushes to non-default branches deploy to a preview environment automatically |

When auto deploy is disabled for an environment, Unkey records each matching push as a **Skipped** deployment for visibility, but no build runs. You can still ship changes by triggering a manual deployment from the dashboard or by [pushing an image with the CLI](/build-and-deploy/cli).

Auto deploy runs after [watch paths](#watch-paths) are evaluated. If auto deploy is off, the deployment is skipped before watch paths are checked.

Common reasons to disable auto deploy:

* Keep production stable and promote releases manually after reviewing a preview deployment
* Avoid noisy preview deployments while iterating on a long-lived feature branch
* Build images in your own CI and push them with the CLI instead

## Runtime settings

Runtime settings control the resources and behavior of your running instances.

### Regions

Geographic regions where your app runs. You must select at least one region. Traffic routes to the nearest healthy region automatically. See [Regions](/build-and-deploy/regions) for the full list of available regions.

Production and preview environments can have different region configurations.

### Instances

The autoscaling range for each region, set as a minimum and maximum number of instances. Unkey runs at least the minimum number of instances in every selected region and scales up to the maximum based on CPU usage. Both values default to 1.

Set the minimum and maximum to the same value to pin instance count and disable autoscaling. Set them to different values to let Unkey scale instances based on load:

* **Minimum replicas** — the fewest instances to keep running per region, even under zero load. Increase this for redundancy or to avoid cold-start latency on the first request.
* **Maximum replicas** — the ceiling Unkey scales up to under peak load.

Production and preview environments can use different ranges. For example, you might run production with a range of `2 – 4` for redundancy and headroom while keeping preview at `1 – 1` to reduce cost.

<Note>
  During the beta, the maximum is 4 instances per region. Contact [support@unkey.com](mailto:support@unkey.com) if you need more.
</Note>

### Autoscaling

When the minimum and maximum replicas differ, Unkey automatically adjusts instance count between those bounds based on CPU utilization. Instances scale up when sustained CPU usage is high and scale back down toward the minimum when load drops.

<Note>
  Advanced autoscaling thresholds (memory, RPS, custom CPU targets) are not yet configurable in the dashboard. Contact [support@unkey.com](mailto:support@unkey.com) if you need to tune them.
</Note>

### CPU

CPU allocation for each instance. Available options:

| Option   | Millicores |
| -------- | ---------- |
| 1/4 vCPU | 256        |
| 1/2 vCPU | 512        |
| 1 vCPU   | 1,024      |
| 2 vCPU   | 2,048      |

Defaults to 1/4 vCPU.

<Note>
  During the beta, the maximum is 2 vCPU. Contact [support@unkey.com](mailto:support@unkey.com) if you need more.
</Note>

### Memory

Memory allocation for each instance. Available options:

* 256 MiB (default)
* 512 MiB
* 1 GiB
* 2 GiB
* 4 GiB

<Note>
  During the beta, the maximum is 4 GiB. Contact [support@unkey.com](mailto:support@unkey.com) if you need more.
</Note>

### Storage

Two writable storage locations are available to your instance:

| Path    | Description                                                           | Always available                |
| ------- | --------------------------------------------------------------------- | ------------------------------- |
| `/tmp`  | Small in-memory tmpdir for scratch files, sockets, and runtime caches | Yes                             |
| `/data` | Dedicated ephemeral disk volume (see below)                           | Only when storage is configured |

#### `/tmp`

Every instance gets a writable `/tmp` directory backed by memory. Use it for small temporary files that your runtime or libraries may need (lock files, Unix sockets, etc.). Because it shares the instance's memory allocation, avoid writing large files here, use ephemeral storage instead.

#### Ephemeral storage

Ephemeral disk space per instance. When configured, Unkey attaches a dedicated volume to each instance mounted at `/data`. The volume is created when the instance starts and destroyed when it stops, data does not persist across restarts.

Available options:

* None (default)
* 512 MiB
* 1 GiB
* 2 GiB
* 5 GiB
* 10 GiB

Use this for workloads that need temporary disk access, such as media processing (ffmpeg), file format conversion, or caching data before uploading to external storage.

Your application can read the mount path from the `UNKEY_EPHEMERAL_DISK_PATH` environment variable, which is set to `/data` when storage is configured.

<Note>
  During the beta, the maximum is 10 GiB. Contact [support@unkey.com](mailto:support@unkey.com) if you need more.
</Note>

### Port

The port your application listens on. Defaults to 8080. Must be between 1 and 65,535.

Unkey injects this value as the `PORT` environment variable at runtime. If your Dockerfile sets `ENV PORT=8080` but you configure port 8081 in your app settings, your application receives `PORT=8081`. Runtime settings always take precedence over defaults set in the container image.

### Upstream protocol

The protocol Unkey uses to forward requests to your application. Available options:

| Option       | Description                                                                                                                     |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| HTTP/1.1     | Standard HTTP protocol. Works with all frameworks and languages. (default)                                                      |
| HTTP/2 (h2c) | Cleartext HTTP/2 for applications that support h2c. Enables multiplexing and header compression between the proxy and your app. |

Defaults to HTTP/1.1. Only change this if your application explicitly supports h2c (HTTP/2 without TLS). Most applications should use HTTP/1.1.

### Command

The command to start your application. This overrides the default `CMD` in your Dockerfile. Leave empty to use your image's default command.

Arguments are split on whitespace. Example: `npm start`.

### Shutdown signal

The signal Unkey sends to your application when stopping an instance during deployments or scale-down. Defaults to `SIGTERM`.

Supported signals:

* `SIGTERM` (default)
* `SIGINT`
* `SIGQUIT`
* `SIGKILL`

Your application should handle the configured signal to shut down gracefully (close connections, flush buffers, finish in-progress requests). If the process doesn't exit within the shutdown timeout, Unkey sends `SIGKILL`.

<Note>
  The shutdown signal is not yet configurable in the dashboard. Contact [support@unkey.com](mailto:support@unkey.com) to change it from the default `SIGTERM`.
</Note>

### Health check

An endpoint Unkey uses to verify your instances are healthy. When configured, Unkey sends periodic HTTP requests to the specified path and uses the response to determine instance health.

| Setting           | Description                                                     | Default |
| ----------------- | --------------------------------------------------------------- | ------- |
| Method            | `GET` or `POST`                                                 | `GET`   |
| Path              | The endpoint path (must start with `/`)                         | -       |
| Interval          | How often to check (for example, `30s`, `2m`, `1h`)             | `30s`   |
| Timeout           | How long to wait for a response before marking the check failed | 5s      |
| Failure threshold | Consecutive failures before marking the instance unhealthy      | 3       |
| Initial delay     | Time to wait after instance start before the first check        | 0s      |

The health check endpoint must return a `2xx` status code to pass. After the failure threshold is reached, Unkey marks the instance as unhealthy and stops routing traffic to it.

Health checks are optional. If you don't configure one, Unkey relies on process-level health monitoring.

<Note>
  Timeout, failure threshold, and initial delay are not yet configurable in the dashboard. Contact [support@unkey.com](mailto:support@unkey.com) to adjust these values.
</Note>

## Environment variables

Environment variables have moved to their own dedicated **Environment Variables** tab in the project dashboard. You can search, filter by environment, sort, and bulk-import variables from `.env` files.

See [Variables](/platform/variables/overview) for full details on creating, editing, and managing variables.

## Networking settings

### Custom domains

Serve your deployment from your own domain name. Each custom domain is scoped to an environment and requires DNS verification before it becomes active.

See [Custom domains](/networking/domains) for setup instructions, including DNS record configuration and verification.

### OpenAPI spec path

The server path where your application serves its OpenAPI specification (for example, `/openapi.yaml` or `/api/spec.json`). When set, Unkey fetches the spec from your running deployment for use with [OpenAPI validation](/platform/sentinel/policies/openapi-validation) and API documentation.

Maximum length is 512 characters. Leave empty to disable spec discovery.

## App-level settings

These settings apply to the app itself, not to a specific environment.

### Default branch

The Git branch that maps to the production environment. Defaults to `main`. Unkey updates this automatically when you connect a GitHub repository.

Pushes to the default branch trigger production deployments. Pushes to any other branch trigger preview deployments.

### Delete protection

When enabled, prevents the app from being deleted. You must disable delete protection before you can delete the app.

<Note>
  Delete protection is not yet configurable in the dashboard. Contact [support@unkey.com](mailto:support@unkey.com) to enable it.
</Note>