Configuration

Taxiway separates installed runtime assets from mutable user state.

Runtime Assets

Release installs place runtime assets under:

~/.taxiway/runtime

The runtime directory contains files needed to create labs:

• infra/
• agents/
• orchestrators/

Override it with TAXIWAY_RUNTIME_DIR when developing from a source checkout.

Lab State

Lab state defaults to:

~/.taxiway/lab-state

Override it with --state-dir <path> or TAXIWAY_LAB_STATE_DIR.

When running Taxiway from a source checkout, an .envrc redirects all state paths into the checkout — see Development.

Drivers

Taxiway supports:

Force a driver for one command:

taxiway up mylab --driver docker

Set a default driver for the shell:

export LAB_DRIVER=docker
taxiway up mylab

Driver resolution order is:

1. --driver <name>
2. LAB_DRIVER
3. auto-detection: Lima when limactl is available, then Docker

See Drivers for Lima and Docker details.

Lima startup timeout

Taxiway allows up to 15 minutes for each Lima VM start, on all platforms. This applies to both lab creation and restarting an existing VM. A ready VM returns immediately; the timeout is a maximum, not a delay.

Override it for a slow machine or first-time downloads:

TAXIWAY_LIMA_START_TIMEOUT=20m taxiway up mylab --driver lima

The value must be a positive duration such as 90s or 20m. Taxiway passes it to Lima and bounds startup plus guest readiness/preparation, honoring an earlier caller deadline or cancellation. Native Lima progress appears while startup runs. On failure, the error retains a bounded output tail, the last reported readiness stage and the instance name. A timeout does not delete the VM; inspect that instance with the suggested limactl list command before retrying or removing it.

Running alone does not prove the guest is ready. Retrying taxiway create checks SSH execution and Lima's native boot-completion marker before marking creation complete. If boot scripts are unfinished, the retry reports that stage and keeps the partial lab available for inspection or a later retry. Use taxiway rm <lab> --yes for targeted cleanup when it is no longer needed.

Gateway

Taxiway starts host-local gateway pieces automatically from lab commands such as taxiway up, taxiway run, and taxiway gateway <lab>. The gateway path uses the shared proxy plus one LiteLLM sidecar per lab.

Lab-specific gateway state lives under each lab:

~/.taxiway/lab-state/<lab>/gateway

Converted provider auth used by gateways lives under:

~/.taxiway/auth

See Gateway.

Observability

Taxiway can manage an optional Langfuse observability stack:

taxiway observe up
taxiway observe open

Initialize the full host-local runtime with:

taxiway init

taxiway init starts the shared proxy and Langfuse. It does not create a lab.

Langfuse is exposed through the Taxiway proxy at http://langfuse.localhost:<proxy-port>. The observability Compose stack does not publish its own host ports.

Mutable observability state lives under:

~/.taxiway/observability

Proxy state lives under:

~/.taxiway/proxy

See Observability.

Shell Completion

Generate completion for the installed CLI:

taxiway completion zsh > ~/.zsh/completions/_taxiway
taxiway completion bash > ~/.bash_completion.d/taxiway
taxiway completion fish > ~/.config/fish/completions/taxiway.fish