Module vm 

Optional session-scoped VM execution (γ CLI / β sidecar): host SessionHolder::Host, Unix γ SessionHolder::Gamma.

Re-exports

pub use sync::pull_workspace_to_vfs;

pub use sync::push_full;

pub use sync::push_incremental;

pub use sync::VmSyncError;

Modules

sync

Push/pull between VFS and a persistent host workspace directory (session VM staging).

Structs

GammaSession

Lima-backed session: sync VFS ↔ host workspace, run tools inside the VM.

HostSandboxSession

Runs rustup/cargo via temp directory export + sync (no persistent VM).

LimaGuestFsOps

Owns a γ GammaSession for GuestFsOps tests and harnesses (delegates to GuestFsOps for GammaSession).

MockGuestFsOps

In-memory GuestFsOps for unit tests (no VM).

VmConfig

Parsed VM-related environment.

Enums

GuestFsError

Errors from GuestFsOps (guest path / remote command).

SessionHolder

Active VM / sandbox backend for one REPL or script run.

VmError

Errors from VM session operations.

WorkspaceMode

How the devshell workspace is backed: memory VFS + push/pull (WorkspaceMode::Sync) vs guest-primary (WorkspaceMode::Guest, planned).

Constants

ENV_DEVSHELL_VM

DEVSHELL_VM — Release / binary default: unset means on (use VM backend per ENV_DEVSHELL_VM_BACKEND). Set to off / 0 / false / no (case-insensitive) to use only the host temp sandbox. on / 1 / true / yes also enable VM mode.

ENV_DEVSHELL_VM_AUTO_BUILD_ESSENTIAL

When unset or truthy (default): after the VM is running, probe for gcc in the guest and, if missing, try apt-get install -y build-essential via non-interactive sudo (requires NOPASSWD or equivalent). Set to 0/false/no/off to skip.

ENV_DEVSHELL_VM_AUTO_BUILD_TODO_GUEST

When 1/true/yes: if guest lacks todo but Cargo workspace is under the Lima mount, run cargo build -p xtask --release --bin todo in the guest (slow; needs cargo + toolchain). Default: off.

ENV_DEVSHELL_VM_AUTO_TODO_PATH

When unset or truthy (default): if target/release from cargo metadata (host cwd) lies under the Lima workspace mount, prepend that path in the guest to PATH when exec limactl shell so todo works without an extra mounts entry. Set to 0/false/no/off to skip.

ENV_DEVSHELL_VM_BACKEND

Backend selector: host, auto, lima, beta, …

ENV_DEVSHELL_VM_BETA_SESSION_STAGING

When set (non-empty), β session_start sends this string as staging_dir to the sidecar instead of canonicalize(DEVSHELL_VM_WORKSPACE_PARENT / …). Use a POSIX path visible to the sidecar process (e.g. /workspace inside a Podman/WSL Linux container) while DEVSHELL_VM_WORKSPACE_PARENT on the host remains the real Windows path for push/pull. See docs/devshell-vm-windows.md (Podman).

ENV_DEVSHELL_VM_CONTAINER_IMAGE

Windows β: OCI image used when no host Linux devshell-vm ELF is found: podman run -i with --serve-stdio and the workspace mounted at /workspace (no host TCP). Default: ghcr.io/tangcan/xtask_todo/devshell-vm:v{CARGO_PKG_VERSION} (published by CI on release).

ENV_DEVSHELL_VM_DISABLE_PODMAN_SSH_HOME

When set (any value), do not isolate USERPROFILE / HOME for podman subprocesses (Windows). By default we point USERPROFILE (Go’s UserHomeDir() on Windows — not only HOME) at a writable temp “profile” with an empty default .ssh/known_hosts, so a locked, protected, or invalid %USERPROFILE%\.ssh\known_hosts is not read. An existing Podman Machine dir is symlinked in when possible (see podman_machine.rs).

ENV_DEVSHELL_VM_EAGER

When 1/true/yes, start the VM session eagerly (future γ); default is lazy start on first rust tool.

ENV_DEVSHELL_VM_GUEST_HOST_DIR

Name of a symlink in the guest $HOME pointing at the host current_dir project (default: host_dir). Set to 0/false/off/no to skip $HOME/<name> and ~/.todo.json symlinks (still cd into the guest project when under the workspace mount).

ENV_DEVSHELL_VM_GUEST_TODO_HINT

When unset or truthy (default): before limactl shell, probe guest for todo and print install hints if missing. Set to 0/false/no/off to skip.

ENV_DEVSHELL_VM_GUEST_WORKSPACE

Guest mount point for that directory (default /workspace).

ENV_DEVSHELL_VM_LIMACTL

Override path to limactl (default: PATH).

ENV_DEVSHELL_VM_LIMA_HINTS

Set to 0/false/no/off to silence Lima configuration hints.

ENV_DEVSHELL_VM_LIMA_INSTANCE

Lima instance name for γ (limactl shell <name>).

ENV_DEVSHELL_VM_LINUX_BINARY

Windows β: optional full Windows path to the Linux devshell-vm binary (x86_64-unknown-linux-gnu / ELF) for podman machine ssh transport.

ENV_DEVSHELL_VM_REPO_ROOT

Windows β: optional Windows path to an xtask_todo repository root (directory containing containers/devshell-vm/Containerfile). Locates target/x86_64-unknown-linux-gnu/release/devshell-vm when ENV_DEVSHELL_VM_LINUX_BINARY is unset. Useful if you keep a checkout for building the sidecar but run cargo devshell from other directories; not applicable when you only have a crates.io install and no clone.

ENV_DEVSHELL_VM_SKIP_PODMAN_BOOTSTRAP

When set (any value), skip podman machine ssh bootstrap on Windows: no Podman check / no requirement that the Linux devshell-vm binary exists (tests or fully manual β setup).

ENV_DEVSHELL_VM_SOCKET

Unix socket path for β client ↔ devshell-vm --serve-socket (see IPC draft).

ENV_DEVSHELL_VM_STDIO_TRANSPORT

Windows β: stdio transport for DEVSHELL_VM_SOCKET=stdio: auto (default), machine-ssh (host ELF + podman machine ssh), or podman-run (OCI image + podman run -i).

ENV_DEVSHELL_VM_STOP_ON_EXIT

When set truthy, run limactl stop on session shutdown.

ENV_DEVSHELL_VM_WORKSPACE_MODE

DEVSHELL_VM_WORKSPACE_MODE — sync (default) or guest (Mode P; guest filesystem as source of truth).

ENV_DEVSHELL_VM_WORKSPACE_PARENT

Host directory we push/pull (must be mounted at super::GammaSession::guest_mount in the Lima VM).

ENV_DEVSHELL_VM_WORKSPACE_USE_CARGO_ROOT

When unset or truthy (default): if ENV_DEVSHELL_VM_WORKSPACE_PARENT is unset, resolve the host workspace directory from cargo metadata in the current directory (Cargo workspace root), so cargo-devshell started from a checkout maps cwd ↔ guest under the same mount prefix. Set to 0/false/no/off to use the legacy default (…/vm-workspace/<instance>/ under the devshell export cache).

Traits

GuestFsOps

Operations on the guest filesystem (Mode P). Paths are guest absolute paths (e.g. /workspace/foo).

VmExecutionSession

Abstraction for a devshell execution session (host temp dir, γ VM, or β sidecar).

Functions

export_devshell_workspace_root_env

guest_path_is_under_mount

True if path is mount or a strict descendant (after normalization). mount is e.g. /workspace.

guest_project_dir_on_guest

Guest directory for the current logical cwd (γ layout: guest_mount + last segment of logical_cwd). Same rule as guest_dir_for_cwd_inner in session_gamma / push layout.

normalize_guest_path

Lexically normalize an absolute Unix-style path (no symlink resolution).

should_delegate_lima_shell

try_session_rc

Build SessionHolder from the environment. On failure (e.g. default γ Lima but limactl missing), writes to stderr and returns Err(()). Use DEVSHELL_VM=off or DEVSHELL_VM_BACKEND=host to force the host temp sandbox.

try_session_rc_or_host

Like try_session_rc, but on failure uses SessionHolder::Host so the REPL can run against workspace_parent_for_instance (same tree as the Lima mount).

vm_workspace_host_root

Host directory that Lima mounts at the guest workspace (e.g. /workspace).

workspace_mode_from_env

Read ENV_DEVSHELL_VM_WORKSPACE_MODE from the environment.

workspace_parent_for_instance

Host workspace root shared with the VM / β staging tree (see docs/devshell-vm-gamma.md).