Deployments

A deployment is a specific version of your code running inside an environment. Each time you push to a mapped branch or trigger a deploy, Phemeral creates a new deployment.

Deployment Lifecycle

Every deployment moves through a series of stages:

1. Building — Phemeral analyzes your project, installs dependencies, and builds the project.
2. Successful — The build completed and the deployment is ready to serve traffic.
3. Failed — The build encountered an error. Check the build logs for details.

A deployment's status is one of: building, successful, or failed.

What Happens During a Deployment

When a deployment is created, Phemeral:

1. Detects your project settings — Python version, framework (FastAPI, Flask, or Django), package manager (uv, poetry, or pip), project root directory, and application entry point. See Project Structure Requirements.
2. Chooses a runtime command — Phemeral uses the project's custom start command if one is saved. Otherwise, it uses the autodetected default command for the framework.
3. Builds your project and assigns compute
4. Assigns a domain — every deployment receives an auto-generated URL in the format {deployment-id}.phemeral.app.

Runtime Command Resolution

Phemeral still autodetects your framework, project root, and application entry point even when you use a custom start command.

That autodetection determines the default runtime behavior. A project-level custom start command only changes the command Phemeral starts for new deployments.

If you clear the custom command later, future deployments fall back to the autodetected default. Existing deployments are not modified.

Build Logs

Each stage of the build is logged with a timestamp. You can view build logs on the deployment detail page in the dashboard.

Domains

Deployments have two types of domains:

• Deployment domain — Auto-generated for every deployment: {deployment-id}.phemeral.app. This always points to the specific deployment, regardless of which deployment is current on the environment.
• Environment domains — Custom subdomains assigned to the environment (e.g. my-api-production.phemeral.app). These point to whichever deployment is currently active on the environment.

When a new deployment is set as the current deployment on its environment, the environment's custom domains begin routing traffic to the new deployment.

Runtime

Deployments run on optimized compute managed by Phemeral's compute orchestration layer.

Compute resources scale to zero when traffic is idle, and scale up (almost) instantly when requests arrive (<75ms).

Setting the Current Deployment

When a deployment triggered by a GitHub push completes successfully, it is automatically set as the current deployment on its environment. The environment's custom domains immediately begin routing traffic to the new deployment.

Runtime Logs

In addition to build logs, you can view runtime logs for a deployment. These are the logs your application produces while handling requests. Runtime logs are available on the deployment detail page and support pagination.