Skip to content
@alexgorbatchev/devhost

Environment Variables

Demo transcript

Automatic bind inputs and service context reach your application.

devhost injects environment variables into each managed service command invocation. Only DEVHOST_BIND_HOST and PORT are operational bind inputs. The remaining variables are context metadata and must not be used as socket bind targets. Undocumented DEVHOST_* variables are reserved for internal supervision and may change without notice.

Operational bind inputs

Section titled “Operational bind inputs”
  • DEVHOST_BIND_HOST
    • the actual interface the child process is expected to listen on
    • use this for binding sockets
  • PORT
    • the listening port selected by devhost
    • injected when the service defines port, including foreground services with port = "auto", unless injectPort = false
    • for port = "auto", startup and configuration reload may retry a clear bind collision; individual service restarts retain the assigned port
    • Restart stack with new ports reassigns automatic ports and relaunches all managed services with refreshed port variables
    • not injected for services that do not define port or for unmanaged services
    • injection only adds PORT to the child process environment; it does not make "$PORT" expand inside a manifest command
    • command = ["storybook", "dev", "--port", "$PORT"] passes literal $PORT; use an explicit shell only when you intentionally need shell expansion
  • injectPort = false
    • service-level opt-out for PORT injection
    • keeps routing and health checks on the configured service port, but does not export PORT into the child process environment
    • useful for wrapper commands that launch multiple dev processes under one top-level command

Routed-service context

Section titled “Routed-service context”
  • DEVHOST_HOST
    • injected only for routed services with host
    • the public routed hostname from the service host field
    • use this when the app needs to know its public development URL or origin
  • DEVHOST_PATH
    • injected only for routed services with host and an explicit path
    • the public routed subpath from the service path field
    • use this when the app needs to mount its router under a specific prefix

Manifest metadata

Section titled “Manifest metadata”
  • DEVHOST_SERVICE_NAME
    • the manifest service key for the current child process
  • DEVHOST_MANIFEST_PATH
    • the absolute path to the resolved devhost.toml

Auto-Injected Service Port Variables

Section titled “Auto-Injected Service Port Variables”

To simplify service discovery without requiring manual template references, devhost also automatically injects the resolved port of every service with a port as an environment variable into all child processes using the format DEVHOST_PORT_<SERVICE_NAME_UPPERCASE>. Non-alphanumeric characters in the service name are replaced with underscores (e.g., postgres-db becomes DEVHOST_PORT_POSTGRES_DB).

For example, if a postgres service has resolved port 5433, every managed service command receives:

Terminal window
DEVHOST_PORT_POSTGRES=5433

This allows programs to dynamically query ports directly from the environment at startup.

These values are snapshots for each process invocation. A configuration reload restarts services whose injected port variables change, including otherwise unchanged consumers. Restart stack with new ports rebuilds these variables for every managed service. Individual restarts keep their assigned port, so other running services retain valid port references. Existing terminal sessions keep their launch environment. See Stack lifecycle for recovery behavior.