Feature Flags

Zeph uses Cargo feature flags to control optional functionality. The remaining optional features are organized into use-case bundles for common deployment scenarios, with individual flags available for fine-grained control.

Use-Case Bundles

Bundles are named Cargo features that group individual flags by deployment scenario. Use a bundle to get a sensible default for your use case without listing individual flags.

Bundle build examples

cargo build --release --features desktop          # TUI agent for daily use
cargo build --release --features ide              # IDE assistant (ACP)
cargo build --release --features server           # headless server/daemon
cargo build --release --features desktop,server   # combined: TUI + server
cargo build --release --features ml               # local model inference
cargo build --release --features ml,metal         # local inference with Metal GPU (macOS)
cargo build --release --features ml,cuda          # local inference with CUDA GPU (Linux)
cargo build --release --features full             # everything except hardware-exclusive/dev-only features
cargo build --release --features full,ml          # everything including local inference
cargo build --release --features full,testing     # full plus mock LLM providers for testing

Bundles are purely additive. All existing --features tui,scheduler style builds continue to work unchanged.

No cli bundle: the default build (cargo build --release, no features) already represents the minimal CLI use case. A separate cli bundle would be a no-op alias.

full does not imply testing: mock LLM providers are a dev-only test double, not something a release binary should ship with full alone. Add testing explicitly if you need zeph-llm’s mock provider outside cargo test.

Built-In Capabilities (always compiled, no feature flag required)

The following capabilities compile unconditionally into every build. They are not Cargo feature flags — there is no #[cfg(feature)] gate and no way to disable them. They are listed here for reference only.

Optional Features

Important

--all-features activates both sqlite and postgres simultaneously, which triggers a compile_error! in zeph-db. Use --features full for local development instead (it defaults to sqlite via the crate’s default features; add postgres explicitly with --no-default-features --features full,postgres for a Postgres build).

Crate-Level Features

zeph-acp exposes its own unstable-* flags for ACP protocol surface still marked unstable upstream. The acp feature in the root crate enables all of them automatically — there is no separate acp-unstable flag.

Session lifecycle handlers that were previously gated behind unstable-session-delete, unstable-session-resume, unstable-logout, unstable-session-add-dirs, and unstable-message-id compile unconditionally — the corresponding upstream ACP features stabilised, and the Zeph Cargo features were removed entirely rather than kept as no-op tombstones.

Disable all unstable-* handlers to build a minimal ACP server without them:

cargo build -p zeph-acp --no-default-features

Build Examples

cargo build --release                                      # default build (scheduler + sqlite + always-on features)
cargo build --release --features desktop                   # TUI dashboard + session + index
cargo build --release --features ide                       # ACP (includes the stabilised unstable-session-* handlers)
cargo build --release --features server                    # gateway + a2a + otel + prometheus + session
cargo build --release --features desktop,server            # combined desktop and server
cargo build --release --features ml,metal                  # local inference with Metal GPU (macOS)
cargo build --release --features ml,cuda                   # local inference with CUDA GPU (Linux)
cargo build --release --features full                      # everything except hardware-exclusive/dev-only features
cargo build --release --features full,testing               # full plus mock LLM providers
cargo build --release --features tui                       # individual flag still works
cargo build --release --features tui,a2a                   # combine individual flags freely

Build Profiles

Build with the CI profile:

cargo build --profile ci