Set a Custom Start Command

Use this guide when your app needs a runtime command different from the one Phemeral detects automatically.

Before You Begin

• A Phemeral project.
• Access to the project's Settings tab.
• A start command that binds your app to port 8000.

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

When to Use a Custom Start Command

Most projects should keep autodetection enabled. Set a custom command only when you need to override the default uvicorn or gunicorn command that Phemeral derives from your app.

Common cases include:

• Your app starts through a wrapper script.
• You need different runtime flags than the defaults.
• Your app entry point is valid, but the detected server command is not the one you want to run.
• A monorepo where you want to specify which service within the repo to run.

Save a Custom Start Command

1. Open your project in the dashboard.
2. Go to the Settings tab.
3. Find the Start Command section.
4. Enter the command you want Phemeral to run inside the deployment VM.
5. Click Save Command.

After the command is saved, the section shows the project as using a Custom start command.

Trigger a New Deployment

The updated command is used for new deployments. Existing deployments keep the command 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 Command

To return to autodetection:

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

When the saved value is empty, Phemeral falls back to its autodetected runtime command. The section shows the project as using Autodetect.

Example Commands

# FastAPI or Django
uvicorn app.main:app --host 0.0.0.0 --port 8000

# Flask
gunicorn app.main:app --bind 0.0.0.0:8000

Notes

• The command should start a web server process that binds to port 8000. Phemeral routes incoming requests to that port.
• If you clear the command later, future deployments go back to using the autodetected default. See Supported Frameworks.