Frost

In project templates, services can reference the environment variables of other services using a specific interpolation syntax.

Database templates automatically provide several built-in reference fields:

• HOST
• PORT
• USERNAME
• PASSWORD
• DATABASE
• DATABASE_URL

To reference a service named postgres, use the syntax ${postgres.VARIABLE_NAME}.

DATABASE_URL: ${postgres.DATABASE_URL}
DB_HOST: ${postgres.HOST}

Frost templates are community-contributed YAML files used to deploy services. They are organized into three distinct categories based on their scope:

• Single-Service Templates (databases/): Used for standalone database services (e.g., postgres, mysql, redis).
• Single-Service Templates (services/): Used for standalone application services (e.g., nginx, httpbin).
• Project Templates (projects/): Used for complete application stacks that consist of multiple pre-configured services (e.g., plausible, ghost).

templates/
  databases/     # Single-service database templates
  services/      # Single-service application templates
  projects/      # Multi-service project templates

Frost organizes resources into several key abstractions:

• Project: A container for related services that share environment variables and a Docker network. Within a project, you can use a service name as a hostname to communicate between services.
• Service: The deployable unit, which can be sourced from a repository or a prebuilt Docker image.
• Object Storage: A single user-facing S3-compatible API endpoint. You manage buckets and access keys directly within Frost.
• Domain: A custom domain attached to a service, used for either proxying traffic or as a redirect.
• Deployment: An immutable record of a deployment that includes logs and status information.

When a pull request is opened against a connected repository, Frost automatically generates a preview environment.

Workflow:

• Cloning: Services from the production environment are cloned into the preview environment.
• Deployment: A deployment runs for the service that matches the repository associated with the PR.
• Feedback: Frost posts a status comment on the PR containing the preview URL and the current deployment status.
• Cleanup: The preview environment is automatically destroyed when the pull request is closed or merged.

A deployment is a record of a service deployment attempt. You can track the progress of a deployment using the following status indicators:

• pending: The deployment is currently queued.
• cloning: The system is cloning the git repository.
• pulling: The system is pulling the Docker image.
• building: The system is building the Docker image.
• deploying: The system is starting the container.
• running: The container is healthy and active.
• failed: The deployment attempt failed.

Frost uses environments to run isolated copies of your services within a single project. There are three types of environments:

• Production: The default environment. It is created automatically for every project and is limited to one per project.
• Preview: Automatically created when a pull request is opened on a connected GitHub repository. These environments clone your production services and are automatically destroyed when the pull request is closed or merged.
• Manual: User-defined environments used for staging, testing, or custom workflows. You can create these from the project page and optionally choose to clone services from an existing environment.

When deploying a service that is already running, Frost uses a zero-downtime deployment strategy to ensure availability. The lifecycle follows these steps:

1. Parallel Startup: New container(s) start alongside the existing ones.
2. Health Checks: Frost runs health checks on the new containers.
3. Traffic Switch: Once the new containers are healthy, traffic is routed to them.
4. Connection Draining: Old containers remain alive to drain existing connections for the duration of drain_timeout seconds.
5. Termination (SIGTERM): After draining, old containers receive a SIGTERM signal.
6. Forceful Shutdown (SIGKILL): If the old containers are still running after shutdown_timeout seconds, a SIGKILL is sent to force them to stop.

Services belonging to the same Frost project can communicate with each other using their service name as the hostname. You do not need to use external IP addresses or complex service discovery; simply use http://<service-name>:<port>.

// Example: Calling a service named 'api' on its default port
http://api:8080/health

You can connect custom domains to your services using two different domain types:

• Proxy: Routes incoming traffic directly to your service.
• Redirect: Performs a URL redirect to another destination. Supports 301 (permanent) and 307 (temporary) status codes.

In multi-service project templates, you can reference environment variables from one service in another using the syntax ${service_name.ENV_VAR_NAME}.

For database services, the following built-in references are available:

• HOST
• PORT
• USERNAME
• PASSWORD
• DATABASE
• DATABASE_URL

services:
  postgres:
    type: database
    # ... configuration ...

  app-service:
    image: my-app:latest
    environment:
      DATABASE_URL: ${postgres.DATABASE_URL}
      DB_HOST: ${postgres.HOST}
      DB_USER: ${postgres.USERNAME}
      DB_PASSWORD: ${postgres.PASSWORD}

Frost uses OAuth 2.1 with PKCE for MCP authentication. The process is browser-based, meaning there are no tokens for you to manually copy-paste during setup:

1. The agent connects to /api/mcp and receives a 401.
2. The agent discovers the auth server via /.well-known/oauth-protected-resource.
3. The agent registers as a client via /api/oauth/register.
4. Your browser opens for you to log in and approve access.
5. The agent receives and stores an access token locally.

Token Management:

• Access tokens expire (default: 30 days).
• You can view or revoke active tokens in Settings → MCP Tokens.
• For programmatic or CI/CD access, use the x-frost-token header with an API key obtained from your Settings.