Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions contracts/python_runtime_gap_report.json
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
{
"version": 1,
"generated_at": "2026-07-06T17:49:55+00:00",
"matrix_generated_at": "2026-07-06T17:49:55+00:00",
"matrix_sha256": "19b3bb085a8392aa9e6f99856983555c06da3606d5e81a6d1f2be7d20022899d",
"generated_at": "2026-07-10T21:33:31+00:00",
"matrix_generated_at": "2026-07-10T21:30:49+00:00",
"matrix_sha256": "9968ef658488512f15c0ebda73d08c82da359ab389b1ff880b585dd47d5bb935",
"summary": {
"feature_count": 59,
"gap_count": 0,
Expand Down
3 changes: 2 additions & 1 deletion contracts/runtime_feature_matrix.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"version": 1,
"generated_at": "2026-07-06T17:49:55+00:00",
"generated_at": "2026-07-10T21:30:49+00:00",
"inventory_sources": {
"python_supported_commands": [
"blast-all",
Expand Down Expand Up @@ -327,6 +327,7 @@
"--deps",
"--deps-parallel",
"--deps-sequential",
"--docker",
"--doctor",
"--entire-system",
"--failed",
Expand Down
4 changes: 4 additions & 0 deletions docs/reference/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -312,6 +312,10 @@ High-value command families:
- `plan`
- `import`
- `test`

When `envctl pr` or `envctl ship` opens a pull request without an explicit
`ENVCTL_PR_BASE`, it selects the first branch that exists in this order:
`dev`, `main`, then `master`. Both remote branches and local refs are checked.
- `logs`
- `health`
- `errors`
Expand Down
59 changes: 59 additions & 0 deletions docs/reference/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -378,6 +378,65 @@ The wizard saves accepted backend/frontend test suggestions to `ENVCTL_BACKEND_T
| `ENVCTL_WORKTREE_CGC_DATABASE` | `kuzudb` | Backend passed as `--database <value>` to `cgc context create` for generated worktree contexts. |

## Execution Policy

### Docker application runtime

`envctl ... --docker` preserves normal project selection, port allocation, dependency startup,
service ordering, state, dashboard, logs, health, restart, and stop behavior, but launches every
selected app service in a managed container instead of as a host process. Managed dependencies such
as Postgres, Redis, Supabase, and n8n continue to use their existing Docker adapters.

Settings resolve service-specific keys before global fallbacks. Additional service names are
uppercased and non-alphanumeric characters become underscores, so `voice-runtime` accepts the
standard `ENVCTL_SERVICE_VOICE_RUNTIME_*` prefix (and the shorter `ENVCTL_VOICE_RUNTIME_*` alias).

| Variable | Default | Purpose |
| --- | --- | --- |
| `ENVCTL_<SERVICE>_DOCKER_IMAGE` / `ENVCTL_DOCKER_IMAGE` | unset | Existing image to run. Without a Dockerfile setting, no build runs. |
| `ENVCTL_<SERVICE>_DOCKERFILE` / `ENVCTL_DOCKERFILE` | discovered | Dockerfile to build; discovery checks the service directory and then project root. |
| `ENVCTL_<SERVICE>_DOCKER_CONTEXT` / `ENVCTL_DOCKER_CONTEXT` | Dockerfile directory | Build context relative to the project root. |
| `ENVCTL_<SERVICE>_DOCKER_TARGET` / `ENVCTL_DOCKER_TARGET` | unset | Optional multi-stage build target. |
| `ENVCTL_<SERVICE>_DOCKER_BUILD_ARGS` / `ENVCTL_DOCKER_BUILD_ARGS` | public frontend env keys | Comma-separated build-arg names or `NAME=value` entries. Named values come from the service env and are not placed on the Docker command line. |
| `ENVCTL_<SERVICE>_DOCKER_COMMAND` / `ENVCTL_DOCKER_COMMAND` | image command | Explicit command executed inside the container. |
| `ENVCTL_<SERVICE>_DOCKER_COMMAND_MODE` / `ENVCTL_DOCKER_COMMAND_MODE` | `image` | `image` keeps the image CMD/ENTRYPOINT; `service` translates and runs envctl's normal service command. |
| `ENVCTL_<SERVICE>_DOCKER_WORKDIR` / `ENVCTL_DOCKER_WORKDIR` | image default | Container working directory. |
| `ENVCTL_<SERVICE>_DOCKER_PORT` / `ENVCTL_DOCKER_PORT` | single exposed image port or allocated host port | Container-side listener port. |
| `ENVCTL_<SERVICE>_DOCKER_BUILD_POLICY` / `ENVCTL_DOCKER_BUILD_POLICY` | `cached` | `cached`, `missing`, or `never`. |
| `ENVCTL_DOCKER_BUILD_TIMEOUT_SECONDS` | `900` | Image build timeout. |
| `ENVCTL_DOCKER_RUN_TIMEOUT_SECONDS` | `120` | Container creation timeout. |

The default `cached` policy invokes `docker build` with BuildKit enabled on every start. Docker
evaluates the context and reuses unchanged layers, while changed source cannot accidentally reuse a
stale whole image. Generated tags are stable for one checkout/worktree, preventing parallel trees
from racing on one tag. Use `missing` for immutable/prebuilt local tags and `never` when image
lifecycle is owned outside envctl.

Containers publish only to `127.0.0.1`, carry `io.envctl.*` ownership labels, and persist their ID,
name, and image in runtime state. Internal URLs and host settings pointing at `localhost` map to
`host.docker.internal`; browser-facing `VITE_*`, `NEXT_PUBLIC_*`, `PUBLIC_*`, CORS, and frontend URL
values remain host-facing. Service env passes through a short-lived mode-`0600` file and is not
rendered into Docker command diagnostics. Normal logs are snapshotted from Docker on demand;
`logs --follow` creates followers only for that command and tears them down on exit, so application
runtime state does not depend on long-lived host helper processes.

```dotenv
ENVCTL_BACKEND_DOCKER_IMAGE=acme/api-dev:latest
ENVCTL_BACKEND_DOCKER_COMMAND=uvicorn app.main:app --host 0.0.0.0 --port 8000
ENVCTL_BACKEND_DOCKER_PORT=8000

ENVCTL_FRONTEND_DOCKERFILE=frontend/Dockerfile
ENVCTL_FRONTEND_DOCKER_CONTEXT=frontend
ENVCTL_FRONTEND_DOCKER_PORT=5173
```

```bash
envctl start --trees --entire-system --docker --headless
envctl health --json
envctl logs --project feature-a-1 --service backend
envctl restart --project feature-a-1 --service backend --docker --headless
envctl stop --project feature-a-1 --entire-system
```

| Variable | Default | Purpose |
| --- | --- | --- |
| `ENVCTL_SERVICE_ATTACH_PARALLEL` | `true` | Run backend+frontend service attach in parallel when both are selected. |
Expand Down
10 changes: 10 additions & 0 deletions docs/reference/important-flags.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,12 +89,22 @@ Plan-agent handoff note: if `--plan --tmux/--omx --headless` starts the implemen
| `--parallel-trees` | Enable parallel tree startup workers. |
| `--parallel-trees-max <n>` | Max parallel tree startup workers. |
| `--service-parallel` / `--service-sequential` | Run backend+frontend startup attach in parallel or sequential mode (default: parallel). |
| `--docker` | Build or reuse images and run backend, frontend, and additional app services as managed Docker containers. |
| `--parallel` / `--sequential` | For `envctl test`, run backend/frontend test suites in parallel or sequential mode (default: parallel for multiple suites, with sequential fallback). Legacy aliases: `--test-parallel` / `--test-sequential`. |
| `--test-parallel-max <n>` | Cap concurrent test suites in parallel mode and pytest-xdist workers when pytest-xdist is explicitly enabled (default suite cap: CPU-aware, max `4`; default pytest workers: current free CPU cores). |
| `--clear-port-state` | Clear saved port reservations/state. |
| `--force` | Free configured ports if needed. |
| `ENVCTL_DOCKER_PREWARM=0\|1` | Enable/disable one-shot Docker daemon prewarm before requirements startup (default: `1`). |
| `ENVCTL_DOCKER_PREWARM_TIMEOUT_SECONDS=<n>` | Timeout for Docker prewarm command (default: `10`). |
| `ENVCTL_<SERVICE>_DOCKER_IMAGE=<image>` | Use an existing image for one app service. `ENVCTL_DOCKER_IMAGE` is the global fallback. |
| `ENVCTL_<SERVICE>_DOCKERFILE=<path>` | Build an app service image from a Dockerfile. `ENVCTL_DOCKERFILE` is the global fallback. |
| `ENVCTL_<SERVICE>_DOCKER_CONTEXT=<path>` | Override the Docker build context; defaults to the Dockerfile directory. |
| `ENVCTL_<SERVICE>_DOCKER_BUILD_ARGS=<names>` | Add comma-separated Docker build-arg names (or `NAME=value` entries); public frontend env keys are passed automatically. |
| `ENVCTL_<SERVICE>_DOCKER_COMMAND=<command>` | Override the image command inside the container. |
| `ENVCTL_<SERVICE>_DOCKER_COMMAND_MODE=image\|service` | Keep image CMD/ENTRYPOINT (default) or run envctl's normal service command. |
| `ENVCTL_<SERVICE>_DOCKER_PORT=<port>` | Override the container-side port while preserving envctl's allocated host port. |
| `ENVCTL_<SERVICE>_DOCKER_WORKDIR=<path>` | Override the image working directory for the service command. |
| `ENVCTL_<SERVICE>_DOCKER_BUILD_POLICY=cached\|missing\|never` | `cached` (default) reuses Docker layers; `missing` builds only when absent; `never` requires an existing image. |
| `ENVCTL_REQUIREMENTS_PORT_MISMATCH_POLICY=adopt_existing\|recreate` | On existing container port mismatch, adopt existing mapping (default) or force recreate. |

## Logs and Debugging
Expand Down
27 changes: 27 additions & 0 deletions docs/user/common-workflows.md
Original file line number Diff line number Diff line change
Expand Up @@ -218,6 +218,33 @@ This is especially useful:
- before CI or agent automation
- when debugging resume surprises

## Run the Same System in Docker

Use `--docker` to preserve envctl's main/trees, selective-service, dependency, dashboard, health,
logs, restart, and stop workflows while replacing app host processes with managed containers:

```bash
envctl start --main --entire-system --docker --headless
envctl start --trees --entire-system --isolated-deps --docker --headless
```

If a service directory contains a `Dockerfile`, envctl builds it with Docker's layer cache. Otherwise,
configure an existing image with `ENVCTL_BACKEND_DOCKER_IMAGE`, `ENVCTL_FRONTEND_DOCKER_IMAGE`, or
the corresponding prefix for an additional app service. Production-oriented images commonly need
`ENVCTL_<SERVICE>_DOCKER_COMMAND` and `ENVCTL_<SERVICE>_DOCKER_PORT` so the service listens on
`0.0.0.0` at the expected container port.

```bash
envctl endpoints --json
envctl health --json
envctl logs --project Main --service backend
envctl restart --project Main --service backend --docker --headless
envctl stop --project Main --entire-system
```

See [Configuration: Docker application runtime](../reference/configuration.md#docker-application-runtime)
for image, Dockerfile, command, port, workdir, target, and cache-policy settings.

## Debug a Bad Interactive Session

Use this when the issue is in the dashboard, selector, spinner, or input flow.
Expand Down
17 changes: 17 additions & 0 deletions python/envctl_engine/actions/action_command_execution_support.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@
"migrate": "run_migrate_action",
}

_BULK_MUTATING_COMMANDS = frozenset({"commit", "migrate", "pr", "ship"})


class ActionSpinner(Protocol):
def start(self) -> None: ...
Expand Down Expand Up @@ -59,6 +61,12 @@ def execute(self) -> int:
self._emit_finish(1, error=error)
return 1

bulk_confirmation_error = self._bulk_confirmation_error(targets)
if bulk_confirmation_error is not None:
print(bulk_confirmation_error)
self._emit_finish(1, error=bulk_confirmation_error)
return 1

handler = self._handler()
if handler is None:
return self.runtime.unsupported_command(self.route.command)
Expand All @@ -70,6 +78,15 @@ def execute(self) -> int:
self._emit_finish(code)
return code

def _bulk_confirmation_error(self, targets: list[object]) -> str | None:
if self.route.command not in _BULK_MUTATING_COMMANDS:
return None
if not bool(self.route.flags.get("all")) or len(targets) <= 1:
return None
if bool(self.route.flags.get("yes")) or bool(self.route.flags.get("force")):
return None
return f"{self.route.command} --all targets {len(targets)} projects and requires --yes or --force"

def _execute_special_worktree_command(self) -> int | None:
if self.route.command == "self-destruct-worktree":
code = self.orchestrator.run_self_destruct_worktree_action(self.route)
Expand Down
13 changes: 12 additions & 1 deletion python/envctl_engine/actions/action_git_state_support.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,10 @@
import subprocess
from typing import Callable

from envctl_engine.shared.git_branch_support import detect_preferred_default_branch
from envctl_engine.shared.git_branch_support import (
PREFERRED_PR_BASE_BRANCHES,
detect_preferred_default_branch,
)


@dataclass(frozen=True, slots=True)
Expand Down Expand Up @@ -87,6 +90,14 @@ def detect_default_branch(git_root: Path, *, git_output: Callable[[Path, list[st
)


def detect_pr_base_branch(git_root: Path, *, git_output: Callable[[Path, list[str]], str]) -> str:
for branch in PREFERRED_PR_BASE_BRANCHES:
for ref in (f"refs/remotes/origin/{branch}", f"refs/heads/{branch}"):
if git_output(git_root, ["rev-parse", "--verify", ref]).strip():
return branch
return detect_default_branch(git_root, git_output=git_output)


def existing_pull_request(
git_root: Path,
branch: str,
Expand Down
2 changes: 1 addition & 1 deletion python/envctl_engine/actions/project_action_domain.py
Original file line number Diff line number Diff line change
Expand Up @@ -337,7 +337,7 @@ def _resolve_pr_base_branch(context: ActionProjectContext, git_root: Path) -> st
explicit = str(context.env.get("ENVCTL_PR_BASE", "")).strip()
if explicit:
return explicit
return detect_default_branch(git_root)
return git_state_support.detect_pr_base_branch(git_root, git_output=_git_output)


_resolve_analyze_mode = review_iteration_support.resolve_analyze_mode
Expand Down
5 changes: 0 additions & 5 deletions python/envctl_engine/debug/debug_utils.py
Original file line number Diff line number Diff line change
Expand Up @@ -84,11 +84,6 @@ def file_lock(path: Path, *, timeout: float) -> Iterator[None]:
except OSError:
pass
handle.close()
try:
if path.exists() and path.stat().st_size == 0:
path.unlink()
except OSError:
pass


def debug_env_value(env: dict[str, str], key: str) -> str | None:
Expand Down
3 changes: 0 additions & 3 deletions python/envctl_engine/planning/worktree_setup_coordinator.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,6 @@ def apply_setup_worktree_selection(
) -> list[ProjectContextLike]:
if not setup_worktree_requested(route):
return project_contexts
if bool(route.flags.get("docker")):
raise RuntimeError("setup-worktrees is not supported in Docker mode.")

multi_entries = coerce_setup_entries(
route=route,
flag_name="setup_worktrees",
Expand Down
2 changes: 2 additions & 0 deletions python/envctl_engine/runtime/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,8 @@ def _effective_prereq_mode(route: Route) -> str:


def _requires_docker(mode: str, config: EngineConfig, *, route: Route | None = None) -> bool:
if route is not None and bool(route.flags.get("docker")):
return True
if route is not None and route.flags.get("launch_dependencies") is False:
return False
if effective_dependency_scope(route, mode) == "shared" and mode == "trees":
Expand Down
Loading
Loading