Processes

Run web servers, background workers, and scheduled jobs from the same codebase and Docker image.

Process types

Type	Description
`web`	Receives HTTP traffic. Gets a public URL, TLS, and `PORT` injected. At least one web process is required for your app to be reachable.
`worker`	Long-running background process. No inbound traffic, no `PORT`. Use for queue consumers or any persistent background task.
`cron`	Runs on a schedule. Specify a cron expression. Suitable for cleanup jobs, email digests, periodic syncs.

All process types share the same Docker image, secrets, and database connections. You only maintain one Dockerfile.

Processes are per-environment

Each environment owns its own process list. The same process name can carry a different command, cron_schedule, or replica counts in each environment — run an experimental worker in dev only, lower a cron's frequency in dev, or test a command change before promoting it to prod. The environment parameter selects which environment you are configuring. Each environment must keep exactly one enabled web process, and the maximum number of processes is governed by that environment's own tier (app-1=1, app-2=2, app-3=4, app-4=8, app-5=16). Creating an environment clones the process list from the source environment you specify.

Adding a process

MCP (Claude Code / Cursor)

configure_process(
  app_name: "my-api",
  process_name: "web",
  process_type: "web",
  command: "gunicorn app:app --bind 0.0.0.0:$PORT",
  health_check_path: "/health",
  environment: "prod"
)

configure_process(
  app_name: "my-api",
  process_name: "worker",
  process_type: "worker",
  command: "python worker.py",
  environment: "prod"
)

configure_process(
  app_name: "my-api",
  process_name: "digest",
  process_type: "cron",
  command: "python -m jobs.digest",
  cron_schedule: "0 9 * * *",
  environment: "prod"
)

CLI

promptship process configure my-api web --type web --command "gunicorn app:app --bind 0.0.0.0:\$PORT" --env prod
promptship process configure my-api worker --type worker --command "python worker.py" --env prod
promptship process configure my-api digest --type cron --command "python -m jobs.digest" --schedule "0 9 * * *" --env prod

Web process

The web process receives all public HTTPS traffic. PromptShip provisions a platform subdomain (my-api-dev.apps.promptship.dev) and TLS automatically.

Your app must listen on $PORT and bind to 0.0.0.0, not localhost. See Env Vars for usage examples.

Use health_check_path to tell the platform which endpoint to probe before marking a deploy as succeeded. The endpoint must return HTTP 200.

Worker process

Workers are long-running processes that start alongside web processes but receive no inbound traffic. Use them for:

Queue consumers (Celery, RQ, BullMQ)
Background processing loops

Workers share all secrets and database connections with the web process. Each process runs its own command — no wrapper scripts needed:

configure_process(
  app_name: "my-api",
  process_name: "worker",
  process_type: "worker",
  command: "celery -A app worker --loglevel=info",
  environment: "prod"
)

The PROCESS_TYPE and PROCESS_NAME env vars are injected into every process if you need runtime branching.

Cron process

Cron processes run on a schedule using standard cron syntax. The container starts, runs to completion, and exits. Cron runs are capped at 1 hour (activeDeadlineSeconds): a run still going at the deadline is terminated, and the next scheduled run starts normally.

# Every day at 9am UTC
0 9 * * *

# Every 15 minutes
*/15 * * * *

# Every Monday at midnight
0 0 * * 1

Cron jobs share the same secrets and database connections as other processes. Logs are available via get_logs / promptship logs after each run.

Disabling vs. removing a process

Disable a process to pause it in one environment while keeping its config — turn a cron off in prod but keep it in dev, or pause a worker in staging — without re-entering its command or schedule to bring it back. Deploys render only enabled processes; disabling the only enabled web process is rejected.

configure_process(app_name: "my-api", process_name: "digest", process_type: "cron", command: "python -m jobs.digest", cron_schedule: "0 9 * * *", environment: "prod", enabled: false)

promptship process configure my-api digest --type cron --command "python -m jobs.digest" --schedule "0 9 * * *" --env prod --disabled

Removing a process

remove_process(app_name: "my-api", process_name: "digest", environment: "prod")

promptship process remove my-api digest --env prod

Removing a process stops and deletes the running container in that environment. The next deploy will not restart it. The only enabled web process cannot be removed — disable it or another process instead.