This guide focuses on how the Python runtime boots, parses commands, chooses behavior, and hands work off to orchestrators.
Use it when you are changing command flow, startup/resume behavior, launcher handoff, or interactive entry conditions.
The active execution path is:
bin/envctlenvctl_engine.runtime.launcher_clienvctl_engine.runtime.cli:mainenvctl_engine.runtime.command_router.parse_routeEngineRuntimeengine_runtime_dispatch.dispatch_command- orchestrator or inspection handler
Why this matters:
- launcher bugs live before Python import even starts
- wrapper-selection policy also lives before launcher handoff: explicit repo-wrapper paths stay local, while bare
envctlcan still hop to an installed command - route-parsing bugs live before
EngineRuntimebehavior - orchestration bugs usually live after
dispatch_command
envctl_engine.runtime.launcher_cli owns:
- repository root resolution
--repohandling- launcher-only subcommands such as
install,uninstall, and launcherdoctor - Python runtime handoff
bin/envctl plus runtime/launcher_support.py own the wrapper-selection policy that runs before launcher_cli starts:
ENVCTL_USE_REPO_WRAPPER=1forces the repo wrapper- explicit wrapper paths use the current wrapper directly
- bare-name invocations keep the installed-command preference when another
envctlshadows the repo wrapper onPATH
Important env exports set before the engine starts include:
RUN_REPO_ROOTRUN_ENGINE_PATHRUN_LAUNCHER_NAMERUN_LAUNCHER_CONTEXT
python/envctl_engine/runtime/cli.py is the real bootstrap layer for the Python engine.
It does all of the following before dispatch:
- initial route parse using enough local config state to honor
ENVCTL_DEFAULT_MODE - local config discovery
.envctlbootstrap gating- full config load into
EngineConfig - final route parse with the resolved config/environment
- prerequisite checks for selected command classes
- exit code normalization
- terminal restore in
finally
That makes runtime/cli.py part of the runtime contract, not just a thin wrapper.
The CLI needs to know enough about the route to decide whether missing local config is allowed.
That means:
- initial parse: uses local config discovery only to infer things like default mode
- final parse: uses full loaded config and final environment view
This is why bootstrap-safe inspect commands work even before .envctl exists.
Commands intentionally allowed without a repo-local .envctl:
helplist-commandslist-targetslist-treesshow-configshow-stateexplain-startup
The config command also has special handling because it is the bootstrap/edit path itself.
If you add a new inspect-only command, decide explicitly whether it belongs in this allowlist.
cli.py also owns command-class-specific prereq checks.
Examples:
gitis required broadlydockeris required for start/plan/restart when managed dependencies are enabledlsofis required when listener-query port availability mode is selectedrichis required for the Python runtime surface
If you add runtime-critical dependencies, add them here instead of letting them fail later with low-quality errors.
EngineRuntime wires together the runtime domains and exposes the facade the orchestrators call through.
Major collaborators include:
- config
- process runner
- process probe
- port planner
- state repository
- terminal UI
- startup/resume/dashboard/action/state orchestrators
- doctor/debug support
Application service startup flows through descriptor construction in startup/service_execution.py before calling
ServiceManager.start_services_with_attach(...). Backend and frontend still keep their specialized prep/env-file logic,
while additional services are built from declarative .envctl ENVCTL_ADDITIONAL_SERVICES entries and share the same
retry, listener detection, log, state, and runtime-map machinery. App descriptors are executed in dependency layers:
ENVCTL_SERVICE_<SUFFIX>_DEPENDS_ON may reference backend, frontend, other additional services, or managed dependency ids.
Unknown references and cycles fail before processes launch; START_ORDER remains the deterministic tie-breaker within a
ready layer.
Managed Supabase records and projections distinguish the Postgres resource from the public API gateway resource. DB_PORT remains the database listener, while SUPABASE_PUBLIC_PORT publishes Kong and backs ENVCTL_SOURCE_SUPABASE_URL. Supabase startup validates both the DB listener and /auth/v1/health, so failures where Postgres is healthy but Auth/Kong is unreachable are reported as dependency failures instead of producing a browser-only login refusal.
Additional services also carry canonical state fields (project, service_slug, public_url, health_url, critical,
degraded, and failure_detail). Critical services fail fast. Non-critical additional services produce degraded service
records with cwd/log/port metadata and allow independent healthy layers to continue, making the failure visible through
state, runtime maps, dashboard, and health --json. The dashboard renderer consumes runtime-map service projections for
additional service rows, so listener sidecars show final rebound URLs plus public/health URLs while non-listener workers
show explicit non-listener status. Stopped dashboard metadata stores arbitrary service slugs, not just backend/frontend.
Direct stop/restart selection normalizes <slug>, service:<slug>, display names, and full service names through the
shared service selector helper; restart target discovery uses canonical project/service_slug state fields when present.
The Textual config wizard exposes the same managed additional-service fields before review/save, so dependency references,
cycles, mode enablement, listener settings, URLs, start order, and criticality are validated before writing .envctl.
Guideline:
- add policy to domain modules
- add composition and cross-domain wiring to
EngineRuntime
runtime/engine_runtime_dispatch.py maps normalized commands to handlers.
Keep it small.
A good dispatch change:
- adds a command branch
- delegates immediately to a specific handler/orchestrator
A bad dispatch change:
- starts embedding business logic
- duplicates route policy that belongs in the parser
- duplicates lifecycle logic that belongs in orchestrators
The runtime does not have one generic "command orchestrator".
Current dispatch families are:
- direct inspection commands
- debug bundle/report helpers
- lifecycle cleanup commands
- startup/resume commands
- dashboard and config commands
- state actions such as logs/health/errors
- project actions such as test/pr/commit/review/migrate
This matters because each family has different assumptions about:
- whether state must already exist
- whether interactive selection is allowed
- whether the command mutates runtime state
- whether headless mode should still work cleanly
If a command feels awkward in its current family, that is usually a design smell worth resolving explicitly instead of bypassing the boundary.
The runtime has two broad command classes:
- inspection commands that answer questions without mutating runtime state
- operational commands that create, reconcile, or destroy state
Inspection commands include:
list-commandslist-targetslist-treesshow-configshow-stateexplain-startup
Operational commands include:
startplanresumerestart(including additional-service slug/display-name selectors)stop(including additional-service slug/display-name selectors and stopped dashboard metadata)stop-allblast-all- dashboard/state/action commands
This split matters for:
- config bootstrap rules
- headless safety
- exit code expectations
- test setup cost
- keeping
show-configandexplain-startupaligned with startup-blocking config such as per-mode startup disablement
Inside the operational side, there is another important split:
- startup/resume/cleanup commands operate on runtime lifecycle
- state actions operate on existing saved state
- action commands operate on selected projects or services and may reuse saved state for targeting
- dashboard commands may route back into all of the above through interactive command dispatch
Startup is primarily coordinated by startup/startup_orchestrator.py.
High-level phases:
- restart pre-stop if command is
restart - mode validation
- shell-budget gate enforcement
- run id / debug session announcement
- project discovery and selection
- port reservation
- requirements startup
- service startup
- artifact persistence
- optional dashboard entry
The orchestrator itself should remain orchestration-heavy, not policy-heavy.
Supporting policy belongs in:
engine_runtime_startup_support.pystartup_selection_support.pystartup_execution_support.pyrequirements_startup_domain.pyservice_bootstrap_domain.py
Resume is coordinated by startup/resume_orchestrator.py.
High-level phases:
- load latest state
- bind debug run id if available
- enforce cutover budgets for resume
- reconcile state truth
- optionally restore missing services
- save reconciled state
- optionally enter interactive dashboard
The important design choice is that resume is truth-driven, not just pointer-driven.
Interactive behavior is split across:
- dashboard backend policy
- selector implementation policy
That split is important:
- dashboard backend can still be legacy by default
- selectors are already Textual-first by default
Do not collapse these into one idea when refactoring.
Key files:
ui/backend_resolver.pyui/backend.pyui/dashboard/orchestrator.pyui/textual/screens/selector/*
The dashboard also has its own command path:
- read one interactive command line
- sanitize and normalize aliases
- parse that command through
parse_route() - inherit current state mode if the command did not set one explicitly
- add interactive-only flags such as
interactive_command - apply dashboard-owned target selection where needed
- dispatch through the normal runtime dispatch path
That is why dashboard command bugs often cross the parser, UI, and orchestrator boundaries at once.
Startup and resume no longer keep all reporting logic inline.
Important files:
startup/startup_progress.pystartup/resume_progress.pystartup/progress_shared.py
Current design:
- orchestrators emit semantic progress points
- progress helpers deduplicate messages and choose output channels
- shared spinner groups own rich progress rendering and spinner lifecycle events
That separation is important for:
- interactive UX consistency
- debug-flight-recorder evidence
- keeping orchestration code readable after feature growth
runtime/command_router.py is the canonical parser contract.
It owns:
- command aliases
- mode tokens
- project flag handling
- boolean/value/pair/special flags
- env-style assignment handling
- supported command inventory
If a behavior is user-visible at the CLI surface, first ask whether it belongs here.
Examples that do belong here:
- new aliases
- new command names
- new supported flags
- default mode semantics
Examples that do not belong here:
- startup sequencing
- runtime truth rules
- dependency startup retries
The CLI normalizes exit codes into:
0: success1: actionable failure2: controlled quit / interrupt
Preserve this shape unless there is a very strong reason not to.
It is especially important for:
- automation
- CI
- agent flows
- compatibility tests
Checklist:
- Add aliases and supported command entry in
runtime/command_router.py. - Decide whether the command is bootstrap-safe.
- Decide whether it is inspection-only or operational.
- Dispatch from
engine_runtime_dispatch.py. - Implement behavior in the right orchestrator or support module.
- Add parser tests, dispatch tests, and behavior tests.
- Update reference and user docs.
Checklist:
- Put the policy in
startup/orruntime/*_support.py, not directly intoEngineRuntime. - Decide whether it affects inspection commands such as
explain-startup. - Emit events if operators or diagnostics need visibility.
- Add tests for happy path, failure path, and headless behavior if relevant.
- Update user docs if the operational story changed.
- putting route policy in orchestrators instead of the parser
- adding config parsing ad hoc instead of through
EngineConfig - changing startup behavior without updating
explain-startup - changing resume truth behavior without checking doctor and debug surfaces
- assuming unsupported compatibility paths are still part of the active runtime contract