App settings

App settings control how Unkey builds and runs your service. Each app 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.

​

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 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.

​

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 for the full list of available regions. Production and preview environments can have different region configurations.

​

Instances

The number of instances running in each region. Defaults to 1.

​

Autoscaling

Unkey can automatically adjust the number of instances based on load. When configured, autoscaling uses these thresholds to decide when to add or remove instances: When any threshold is exceeded, Unkey adds instances up to the maximum. When utilization drops below the threshold, Unkey removes instances down to the minimum.

​

CPU

CPU allocation for each instance. Available options: Defaults to 1/4 vCPU.

​

Memory

Memory allocation for each instance. Available options:

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

​

Port

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

​

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.

​

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. 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.

​

Sentinel settings

Sentinel settings control how the Sentinel processes requests before they reach your app.

​

Keyspaces

Select one or more keyspaces to enforce API key authentication. When configured, the Sentinel verifies API keys against the selected keyspaces before requests reach your application. Requests with missing or invalid keys receive a 401 response. See API key authentication for details on how verification works and what your application receives via the Principal header.

​

Policy configuration

Each Sentinel policy has these fields: Keyspace authentication is the only policy type configurable from the dashboard. For other policy types (rate limiting, IP rules, OpenAPI validation), see Policies and contact support@unkey.com for configuration.

​

Environment variables

Encrypted key-value pairs injected into your instances at runtime. Variables are scoped to a specific environment, so production and preview can have different values. Each variable has a visibility type: Use write-only for secrets like API keys and database passwords. Use recoverable for non-sensitive configuration like feature flags and service URLs. You can add variables one at a time, paste them in bulk, or drag and drop a .env file. See Variables for details.

​

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 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 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.