Set a Custom Root Directory

Use this guide when your application lives in a subdirectory and Phemeral's default project root detection is not the directory you want to deploy.

Before You Begin

• A Phemeral project connected to a repository.
• Access to the project's Settings tab.
• The repository path to the Python service you want Phemeral to build and run.

Phemeral saves the custom root directory at the project level. New deployments for that project use the saved directory until you clear it.

When to Use a Custom Root Directory

Most projects should keep autodetection enabled. Set a custom root directory only when Phemeral should look in a specific subdirectory for dependency files and your app entry point.

Common cases include:

• A monorepo where your Python backend lives under a folder such as backend/ or services/api/.
• A repository that contains multiple deployable services.
• A repository where the shallowest dependency file belongs to a different tool or service than the one you want to deploy.

Save a Custom Root Directory

1. Open your project in the dashboard.
2. Go to the Settings tab.
3. Find the Root Directory section.
4. Enter the path to your app directory, relative to the repository root.
5. Click Save Root Directory.

After the directory is saved, the section shows the project as using Custom root detection.

Path Requirements

The saved path must:

• Be relative to the repository root.
• Point to a directory in the repository.
• Stay inside the repository.

The path must not:

• Start with /.
• Use .. to move outside the repository.

Examples:

backend
services/api
apps/customer-service

What Changes After You Save It

For future deployments, Phemeral starts dependency and app discovery inside the saved directory instead of searching from the repository root.

Within that directory, Phemeral still uses the normal detection rules:

• Dependency files are checked in this order: uv.lock, poetry.lock, pyproject.toml, then requirements.txt.
• The shallowest matching dependency file inside the selected directory wins.
• App discovery runs from that same directory.

This is useful when your repository contains multiple Python projects but only one of them should be deployed by this Phemeral project.

Trigger a New Deployment

The updated root directory is used for new deployments. Existing deployments keep the configuration they were built with.

To apply the change:

• With GitHub CD: Push a new commit to a mapped branch.
• Without GitHub CD: Create a new deployment from the dashboard.

Clear the Custom Root Directory

To return to autodetection from the repository root:

1. Open the project's Settings tab.
2. In Root Directory, remove the saved value.
3. Click Save Root Directory.

When the saved value is empty, Phemeral falls back to autodetecting the project root from the repository root. The section shows the project as using Autodetect.

Notes

• The directory is repository-relative, not an absolute filesystem path.
• If the saved directory does not exist in a future commit, that deployment will fail during project detection.
• A custom root directory only changes where Phemeral looks for dependency files and the app entry point. It does not change your repository contents.
• If you also need to override how the app starts, see Set a Custom Start Command.