Skip to main content
Use Multiple Services when one repository contains more than one application that should build or run independently. This is common for a monorepo with a web app and API, or for an API with a background worker. Pxxl keeps the services under one project while giving each service its own directory, commands, port, and routing behavior.

​
When to use it

  • A web app and API live in the same repository.
  • A backend and worker share packages or a lockfile.
  • Several applications share one monorepo but need separate public routes.
  • A worker should deploy with the project but should not receive public traffic.

​
Service settings

Each service has its own deployment settings:

​
Example monorepo

This layout keeps the web app and API in one Turborepo workspace:
Configure the services like this: The shared lockfile can be installed from the repository root. Service build commands can then use workspace filters, such as pnpm --filter @pxxl/turbo-web run build.

​
Example API and worker project

For an API and worker, use a public route for the API and keep the worker private: The worker still builds and runs with the project, but Pxxl does not publish a public hostname for it.

​
Configure it in Deploy

1

Enable Multiple Services

In Deploy > Build Configuration, turn on Multiple Services after selecting the repository.
2

Add each service

Give every service an alias, select its base directory, choose its type, and decide whether it needs a public route.
3

Set ports and commands

Add the install, build, and start commands for each service. Confirm that every running service uses the port assigned to it.
4

Review and deploy

Check the service list, secrets, domains, and resource settings before selecting Deploy Project.

​
Configure services with pxxl.toml

Use [services.<alias>] when a saved service needs build settings that differ from repository detection:
The alias in pxxl.toml must match the saved service alias. See pxxl.toml for every service override.

​
Domains and service routes

Attach a domain to the service that should receive its traffic. For CLI workflows, pass the service target when connecting the domain:
Use the API or web service for public traffic. Keep workers, queues, and scheduled processes un-routed unless they must receive HTTP requests.
If a service fails to start, check its base directory, working directory, port, and start command first. A command that works from the repository root may fail when it runs from a service directory.