Support selecting the container engine (docker or Apple Container)

[fnando]

What

Adds a --engine <docker|apple-container> flag (and STELLAR_CONTAINER_ENGINE env var) to stellar container start|stop|logs, letting users pick which container runtime the CLI shells out to. docker remains the default, so existing behavior is unchanged. Selecting apple-container runs Apple's container CLI (macOS 26+, Apple silicon) instead.

Because Apple's runtime has no host concept, --docker-host/DOCKER_HOST is now ignored for non-docker engines with an advisory warning rather than being silently passed through.

Implementation notes:

• All engine-specific behavior is centralized in container/shared.rs: an Engine enum drives per-operation command builders (pull/run/stop/logs), so the only divergences live in one place — Apple uses container image pull and omits docker's --tail all.
• Error messages are now engine-aware ("is container installed and on your PATH?").
• stderr classification for "already running" / "not found" is per-engine; the Apple strings (already exists / not found) were confirmed against the real CLI.
• Follow-up command hints from start carry --engine over; STELLAR_CONTAINER_ENGINE is registered in stellar env; and stellar doctor reports whether the effective engine is installed.

Apple Container

$ $stellar container start --engine apple-container --protocol-version 27
ℹ️ Starting local network
✅ Started container
🔎 Watch logs with `stellar container logs local --engine apple-container`
ℹ️ Stop the container with `stellar container stop local --engine apple-container`

$ container ls | grep stellar
stellar-local  docker.io/stellar/quickstart:testing  linux  arm64  running  192.168.64.7/24  4     1024 MB  2026-07-13T14:52:55Z

$ $stellar container logs --engine apple-container
Starting Stellar Quickstart
versions:
  quickstart: 16a57418b555ab859e133550c449ff15c2f5c06e
  xdr:
    stellar-xdr 27.0.0 (5262803470be965e42f80023d12fba12808c774a)
    xdr: 68fa1ac55692f68ad2a2ca549d0a283273554439
    features: <none>
  core:
    v27.0.0
    ledger protocol version: 27
    rust version: rustc 1.95.0 (59807616e 2026-04-14)
    soroban-env-host versions:
    ...

$ $stellar container stop --engine apple-container
ℹ️ Stopping local container
✅ Container stopped

$ container ls | grep stellar | wc -l
       0

Apple Container using STELLAR_CONTAINER_ENGINE

$ export STELLAR_CONTAINER_ENGINE=apple-container

$ $stellar container start --protocol-version 27
ℹ️ Starting local network
✅ Started container
🔎 Watch logs with `stellar container logs local --engine apple-container`
ℹ️ Stop the container with `stellar container stop local --engine apple-container`

$ container ls | grep stellar
stellar-local  docker.io/stellar/quickstart:testing  linux  arm64  running  192.168.64.8/24  4     1024 MB  2026-07-13T14:57:22Z

$ $stellar container stop
ℹ️ Stopping local container
✅ Container stopped

$ container ls | grep stellar | wc -l
       0

Docker

$ $stellar container start --protocol-version 27
ℹ️ Starting local network
ℹ️ testing: Pulling from stellar/quickstart
ℹ️ Digest: sha256:3b98cc624a235215bbb2dedd18bd3ec3a498053b6b6533533b6a0d94354a7885
ℹ️ Status: Image is up to date for stellar/quickstart:testing
✅ Started container
🔎 Watch logs with `stellar container logs local`
ℹ️ Stop the container with `stellar container stop local`

$ docker container ls | grep stellar
7412897d045d   stellar/quickstart:testing   "/start --local '--e…"   22 seconds ago   Up 22 seconds   5432/tcp, 6060-6061/tcp, 8002/tcp, 8100/tcp, 11625-11626/tcp, 0.0.0.0:8000->8000/tcp, [::]:8000->8000/tcp   stellar-local

$ $stellar container logs
Starting Stellar Quickstart
versions:
  quickstart: 16a57418b555ab859e133550c449ff15c2f5c06e
  xdr:
    stellar-xdr 27.0.0 (5262803470be965e42f80023d12fba12808c774a)
    xdr: 68fa1ac55692f68ad2a2ca549d0a283273554439
    features: <none>
  core:
    v27.0.0
    ...

$ $stellar container stop
ℹ️ Stopping local container
✅ Container stopped

$ docker container ls | grep stellar | wc -l
       0

stellar doctor

$ PATH=/Users/fnando/Projects/stellar/stellar-cli/target/debug stellar doctor 2>/dev/stdout | grep Container
⚠️ Container engine `docker` is not installed

$ STELLAR_CONTAINER_ENGINE=apple-container PATH=/Users/fnando/Projects/stellar/stellar-cli/target/debug stellar doctor 2>/dev/stdout | grep Container
⚠️ Container engine `apple-container` is not installed

$ STELLAR_CONTAINER_ENGINE=docker PATH=/Users/fnando/Projects/stellar/stellar-cli/target/debug stellar doctor 2>/dev/stdout | grep Container
⚠️ Container engine `docker` is not installed

$ STELLAR_CONTAINER_ENGINE=docker $stellar doctor 2>/dev/stdout | grep Container
⚠️ Container engine `docker` is not installed

$ STELLAR_CONTAINER_ENGINE=docker $stellar doctor 2>/dev/stdout | grep Container
✅ Container engine `docker` is available

$ STELLAR_CONTAINER_ENGINE=apple-container $stellar doctor 2>/dev/stdout | grep Container
✅ Container engine `apple-container` is available

Why

PR #2629 replaced the bollard Docker API client with direct docker CLI invocations. Now that we shell out to an external binary, supporting other docker-compatible runtimes is straightforward. Apple's container is the immediate target, giving macOS users a native-VM alternative without Docker Desktop.

Tested end-to-end against a real Apple container install: full start → logs → stop lifecycle, the host-ignored warning, engine-aware not-found error, and env-var selection all verified. Added a fake-engine-on-PATH integration suite (tests/it/container.rs, 9 tests) covering argv propagation, stderr mapping, engine selection, and the binary-missing error, plus unit tests for the builders and classifiers.

Known limitations

Apple's container requires macOS 26 on Apple silicon and, unlike docker, does not support remote hosts, so --docker-host is inert (with a warning) when that engine is selected.

[Copilot]

Pull request overview

Adds support for selecting which container runtime the CLI shells out to for stellar container start|stop|logs, defaulting to docker while enabling Apple’s container CLI via --engine apple-container or STELLAR_CONTAINER_ENGINE. The change centralizes engine-specific command building and stderr classification, and wires engine awareness into diagnostics and integration tests.

Changes:

• Introduce an Engine enum and engine-aware command builders/classifiers for pull/run/stop/logs.
• Add --engine <docker|apple-container> and STELLAR_CONTAINER_ENGINE, including host-ignored warnings for non-docker engines.
• Extend stellar doctor, env var visibility, and integration tests to cover engine selection/argv propagation.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
FULL_HELP_DOCS.md	Documents --engine for container commands (also includes an unrelated stellar xdr docs change).
cmd/soroban-cli/src/env_vars.rs	Registers CONTAINER_ENGINE so STELLAR_CONTAINER_ENGINE is surfaced in env tooling.
cmd/soroban-cli/src/commands/doctor.rs	Adds a doctor check to report whether the selected/default container engine binary is available.
cmd/soroban-cli/src/commands/container/stop.rs	Switches to engine-aware stop command + engine-aware stderr mapping and host-ignored warnings.
cmd/soroban-cli/src/commands/container/start.rs	Switches to engine-aware pull/run commands + engine-aware stderr mapping and host-ignored warnings.
cmd/soroban-cli/src/commands/container/shared.rs	Implements Engine, engine resolution, engine-aware command builders, warnings, and unit tests.
cmd/soroban-cli/src/commands/container/mod.rs	Exposes shared module within the crate for doctor integration.
cmd/soroban-cli/src/commands/container/logs.rs	Uses engine-aware logs command and emits host-ignored warnings.
cmd/crates/soroban-test/tests/it/main.rs	Registers new container integration test module on Unix.
cmd/crates/soroban-test/tests/it/container.rs	Adds integration tests using fake engines on PATH to validate argv propagation and behavior.