Runtime Topology

Runtime topology describes how an App's runtimes are hosted: together in one process or split across explicit commands.

Apps and runtimes are different:

• an App is the runnable boundary, such as app or marketplace
• a Runtime is a process role inside an App, such as HTTP, jobs, or scheduler

Local Default

The default local path is:

forj app

This starts enabled runtimes together for the default app.

For a named app:

forj marketplace app

Split Runtimes

Run a specific runtime when you want separate process boundaries:

forj api
forj worker
forj scheduler

For a named app:

forj marketplace api
forj marketplace worker
forj marketplace scheduler

The application behavior should not change when you split runtimes. Only process topology changes.

Built Binaries

Deployment docs use built binaries:

./bin/app
./bin/app api
./bin/app worker
./bin/app scheduler

For runtime-capable Apps, the bare binary defaults to run without a build flag and is equivalent to ./bin/app run. Explicit commands still take precedence, and CLI-only binaries retain root help behavior when launched without a command.

Named app binaries follow the App name:

./bin/marketplace api
./bin/marketplace worker

Runtime Defaults

Generated internal/runtime/apps.go gives each app deterministic local defaults.

App	HTTP	Metrics	Scheduler metrics	Worker metrics
app	3000	10000	10001	10002
first named app	3001	10010	10011	10012
second named app	3002	10020	10021	10022

Named apps do not consume default-app globals such as PORT=3000. Override one app with its uppercase app prefix:

MARKETPLACE_PORT=3100
MARKETPLACE_METRICS_PORT=10110

Observability Identity

Operational data should preserve:

• project identity
• app identity
• runtime or process role
• instance identity when there are replicas

Metrics scrape labels currently include app, process, service, and environment.

Choosing a topology

Use the combined runtime first for:

• local development
• onboarding
• simple deployments

Use split runtimes when:

• HTTP and workers scale independently
• scheduler should run as a singleton
• queue workers need separate resource limits
• process supervision differs by runtime

Common Mistakes

Common mistakes

• Do not create a named app just to split HTTP from workers.
• Do not make business logic depend on whether runtimes run together or separately.
• Do not expect process-local drivers to become shared infrastructure in distributed topology.
• Do not run multiple scheduler replicas unless the scheduler and deployment are configured for it.

Next Steps

• Apps explains the default app and named apps.
• Runtime Lifecycle explains startup and shutdown ordering.
• Runtime Processes explains production process deployment.