Taxiway

https://taxiway.sh/docs
Admin
Taxiway creates isolated labs for running and comparing AI agent orchestrators on Lima or Docker,...
Tokens:20,135
Snippets:239
Trust Score:2.2
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install latest release

Source: https://taxiway.sh/docs/contributing/release

Command to download and execute the latest installation script.

```bash
curl -fsSL https://github.com/taxiway-sh/taxiway/releases/latest/download/install.sh | sh
```

--------------------------------

### Start full local runtime with taxiway init and observe open

Source: https://taxiway.sh/docs/how-to/observability

Run `taxiway init` to start the shared proxy and Langfuse observability stack, then `taxiway observe open` to open the Langfuse web UI. This does not create a lab or start a lab LiteLLM gateway.

```bash
taxiway init
taxiway observe open

```

--------------------------------

### Start a recording

Source: https://taxiway.sh/docs/how-to/recordings

Starts a recording for the specified lab.

```bash
taxiway record start mylab
```

--------------------------------

### Install Taxiway with curl

Source: https://taxiway.sh/docs/reference/installation

Downloads and runs the Taxiway installer script from taxiway.run.

```bash
curl -fsSL https://taxiway.run | sh

```

--------------------------------

### Install to explicit binary directory

Source: https://taxiway.sh/docs/contributing/release

Command to install the binary to a custom directory using the --bin-dir flag.

```bash
curl -fsSL https://github.com/taxiway-sh/taxiway/releases/latest/download/install.sh | sh -s -- --bin-dir "$HOME/bin"
```

--------------------------------

### Start only Langfuse and proxy with observe up and open

Source: https://taxiway.sh/docs/how-to/observability

Use `taxiway observe up` to start Langfuse and the proxy together without a lab, then `taxiway observe open` to open the Langfuse web UI.

```bash
taxiway observe up
taxiway observe open

```

--------------------------------

### Start a lab with a repository

Source: https://taxiway.sh/docs/reference/concepts

Initializes a lab and mirrors the specified remote repository into a local bare Git repository for the orchestrator to use.

```bash
taxiway up mylab --type <type> --repo https://github.com/org/repo
```

--------------------------------

### Serve the browser player

Source: https://taxiway.sh/docs/how-to/recordings

Starts a local HTTP server to serve the browser player for a specific lab.

```bash
taxiway record player mylab
```

--------------------------------

### Start observability and attach to lab session

Source: https://taxiway.sh/docs/how-to/gateway

Initialize observability, refresh the gateway, and attach to the lab session to enable trace export.

```bash
taxiway observe up
taxiway gateway <lab>
taxiway shell <lab>

```

--------------------------------

### Run site tests and build

Source: https://taxiway.sh/docs/contributing/testing

Installs site dependencies, runs the site tests, and builds the production site. Use this for documentation or site changes.

```shell
cd site
npm ci
npm test
npm run build

```

--------------------------------

### Install explicit release version

Source: https://taxiway.sh/docs/contributing/release

Command to download and execute the installation script for a specific version tag.

```bash
curl -fsSL https://github.com/taxiway-sh/taxiway/releases/download/v0.1.0/install.sh | sh
```

--------------------------------

### Quick Start Codex Lab

Source: https://taxiway.sh/docs/orchestrators/codex

Initialize a new Codex lab and attach to the session.

```bash
taxiway up mylab --type codex --repo https://github.com/org/repo
taxiway shell mylab
```

--------------------------------

### Run Install integration workflow from command line

Source: https://taxiway.sh/docs/contributing/installation-qualification

Use this command to trigger the Install integration workflow from the command line. It runs the workflow on the main branch with the release input set to 'latest'. Use an explicit release tag to qualify a specific version.

```bash
gh workflow run install.yml --repo taxiway-sh/taxiway \
  --ref main -f release=latest

```

--------------------------------

### Start and shell into a Gas Town lab

Source: https://taxiway.sh/docs/orchestrators/gastown

Starts a Gas Town lab and opens a shell in its crew directory. The repo is resolved by Git on the host before the lab uses a local bare mirror. Run `taxiway observe up` separately to enable Langfuse traces.

```bash
taxiway up mylab --type gastown --repo https://github.com/org/repo
taxiway shell mylab

```

--------------------------------

### Start or refresh a lab gateway with taxiway gateway

Source: https://taxiway.sh/docs/how-to/observability

Run `taxiway gateway <lab>` to start or refresh the lab gateway. Then run model traffic through it; successful LiteLLM calls appear in Langfuse when the lab has generated Langfuse keys.

```bash
taxiway gateway <lab>

```

--------------------------------

### Start a named recording

Source: https://taxiway.sh/docs/how-to/recordings

Starts a recording for the specified lab with a stable name for future reference.

```bash
taxiway record start mylab --name delivery-run
```

--------------------------------

### Initialize full host-local runtime

Source: https://taxiway.sh/docs/reference/configuration

Initialize the full host-local runtime with taxiway init. Starts the shared proxy and Langfuse, but does not create a lab.

```bash
taxiway init
```

--------------------------------

### Start Lima VM with limactl

Source: https://taxiway.sh/docs/drivers/lima

Command used by the driver to start a Lima VM instance using a rendered YAML template.

```bash
limactl start --name=<id> <rendered-yaml>
```

--------------------------------

### Initialize Taxiway

Source: https://taxiway.sh/docs/reference/installation

Initializes Taxiway. The first run downloads and starts shared services, which can take a few minutes.

```bash
taxiway init

```

--------------------------------

### Check Taxiway installation

Source: https://taxiway.sh/docs/reference/installation

Checks that Docker is available and the shared services are running.

```bash
taxiway status

```

--------------------------------

### Conventional Commits examples

Source: https://taxiway.sh/docs/contributing/development

Examples of valid commit messages following the Conventional Commits specification.

```text
feat: add a new capability
feat(record): support explicit window sizing
fix: correct broken behavior
cleanup: remove obsolete behavior
docs: update documentation
```

--------------------------------

### Get live proxy port with taxiway access and status

Source: https://taxiway.sh/docs/how-to/observability

Use `taxiway access` and `taxiway status` to get the live command output and find the exact proxy port instead of guessing.

```bash
taxiway access
taxiway status

```

--------------------------------

### Get gateway access

Source: https://taxiway.sh/docs/how-to/gateway

Run to print the LiteLLM UI URL, OpenAI-compatible API URL, and lab gateway key.

```bash
taxiway access
```

--------------------------------

### Quick Start: Initialize and Access Claude Code Lab

Source: https://taxiway.sh/docs/orchestrators/claude-code

Commands to provision a lab with the claude-code type and attach to the tmux session.

```bash
taxiway up mylab --type claude-code --repo https://github.com/org/repo
taxiway shell mylab
```

--------------------------------

### Runtime assets directory

Source: https://taxiway.sh/docs/reference/configuration

Default location for installed runtime assets. Override with TAXIWAY_RUNTIME_DIR when developing from a source checkout.

```bash
~/.taxiway/runtime
```

--------------------------------

### Print lab endpoint and key

Source: https://taxiway.sh/docs/how-to/gateway

Prints the lab endpoint and key, including the actual proxy port. Use this to get the lab-specific hostname and port for the gateway.

```bash
taxiway access

```

--------------------------------

### End-to-end test file build tag directive

Source: https://taxiway.sh/docs/contributing/testing

End-to-end test files must start with this directive and a blank line. The build tag `e2e` ensures these tests are only compiled when the e2e build tag is set.

```go
//go:build e2e


```

--------------------------------

### Inspect adapter details with taxiway describe

Source: https://taxiway.sh/docs

Use this command to inspect the configuration and provisions provided by a specific adapter type.

```bash
taxiway describe <type>
```

--------------------------------

### Default Langfuse proxy endpoint

Source: https://taxiway.sh/docs/how-to/observability

When Taxiway is installed, the default proxy endpoint is usually http://langfuse.localhost:4000.

```text
http://langfuse.localhost:4000

```

--------------------------------

### Build the Taxiway binary

Source: https://taxiway.sh/docs/contributing/development

Build the project binary and verify the version.

```bash
go build -o ./taxiway ./cmd/taxiway
./taxiway version
```

--------------------------------

### Describe Codex Adapter

Source: https://taxiway.sh/docs/orchestrators/codex

Inspect the configuration and details of the codex adapter.

```bash
taxiway describe codex
```

--------------------------------

### Build all packages via Makefile

Source: https://taxiway.sh/docs/contributing/development

Use the Makefile to build all project packages.

```makefile
make build
```

--------------------------------

### List runtime model catalog

Source: https://taxiway.sh/docs/how-to/gateway

Shows the path to the runtime LiteLLM model catalog.

```bash
~/.taxiway/runtime/infra/gateway/litellm/models.yaml
```

--------------------------------

### Build a local snapshot

Source: https://taxiway.sh/docs/contributing/development

Build a GoReleaser snapshot for local testing of the packaging path.

```makefile
make snapshot
```

--------------------------------

### Set up Codex subscription routing

Source: https://taxiway.sh/docs/how-to/gateway

Converts host Codex auth into LiteLLM format for ChatGPT subscription-backed Codex models. Requires existing host Codex login at ~/.codex/auth.json.

```bash
codex login
taxiway credentials codex
taxiway gateway <lab>
```

--------------------------------

### Inspect the Gas Town adapter

Source: https://taxiway.sh/docs/orchestrators/gastown

Displays the Gas Town adapter's settings and behavior.

```bash
taxiway describe gastown

```

--------------------------------

### Override end-to-end test timeout

Source: https://taxiway.sh/docs/contributing/testing

Sets the `E2E_TIMEOUT` environment variable to 1800 seconds for the `gastown` orchestrator's `up` scenario. Useful for slow downloads or first-run setup.

```shell
E2E_TIMEOUT=1800s make test-e2e-gastown-up

```

--------------------------------

### Load .envrc for local development

Source: https://taxiway.sh/docs/contributing/development

Source the .envrc file to configure the local development environment.

```bash
source .envrc
```

--------------------------------

### Sanitized crew directory path

Source: https://taxiway.sh/docs/orchestrators/gastown

Crew directory path after sanitizing the rig name. Hyphens, dots, spaces, and path separators are replaced with `_`; for example, `agentic-clm-demo` becomes `agentic_clm_demo`.

```bash
$HOME/gt/agentic_clm_demo/crew/<lab_sanitized>

```

--------------------------------

### Create and push a semver tag

Source: https://taxiway.sh/docs/contributing/release

Commands to create a new version tag and push it to the origin repository to trigger the release workflow.

```bash
git tag v0.1.0
git push origin v0.1.0
```

--------------------------------

### List all recordings

Source: https://taxiway.sh/docs/how-to/recordings

Lists recordings across all labs.

```bash
taxiway record list
```

--------------------------------

### Run unit tests and linting

Source: https://taxiway.sh/docs/contributing/development

Execute unit tests and linting checks.

```makefile
make test-unit
make lint
```

--------------------------------

### Run unit and shell script tests

Source: https://taxiway.sh/docs/contributing/testing

Runs the unit tests with `make test-unit` and the shell script tests with `make test-scripts`. These provide quick feedback during development and do not require Docker or a running lab.

```shell
make test-unit
make test-scripts

```

--------------------------------

### Override Lima startup timeout

Source: https://taxiway.sh/docs/reference/configuration

Set TAXIWAY_LIMA_START_TIMEOUT to override the default 15-minute Lima VM startup timeout. Value must be a positive duration like 90s or 20m.

```bash
TAXIWAY_LIMA_START_TIMEOUT=20m taxiway up mylab --driver lima
```

--------------------------------

### Run against source-tree runtime assets

Source: https://taxiway.sh/docs/contributing/release

Command to run the taxiway binary using local runtime assets during development.

```bash
TAXIWAY_RUNTIME_DIR=$PWD go run ./cmd/taxiway version
```

--------------------------------

### Inspect Claude Code Adapter

Source: https://taxiway.sh/docs/orchestrators/claude-code

Command to display configuration and details for the claude-code adapter.

```bash
taxiway describe claude-code
```

--------------------------------

### Check GoReleaser configuration

Source: https://taxiway.sh/docs/contributing/release

Command to validate the current GoReleaser configuration file.

```bash
goreleaser check
```

--------------------------------

### Create local snapshot artifacts

Source: https://taxiway.sh/docs/contributing/release

Command to generate local release artifacts without creating a formal release.

```bash
goreleaser release --snapshot --clean
```

--------------------------------

### Run end-to-end tests

Source: https://taxiway.sh/docs/contributing/development

Execute Docker-backed end-to-end tests.

```makefile
make test-e2e
```

--------------------------------

### Configure Codex Credentials

Source: https://taxiway.sh/docs/orchestrators/codex

Authenticate with Codex Pro by logging in on the host and syncing credentials to Taxiway.

```bash
codex login
taxiway credentials codex
```

--------------------------------

### Open Langfuse to view traces

Source: https://taxiway.sh/docs/how-to/gateway

Opens the Langfuse UI to inspect exported traces.

```bash
taxiway observe open

```

--------------------------------

### Manage Langfuse observability stack

Source: https://taxiway.sh/docs/reference/configuration

Commands to bring up and open the optional Langfuse observability stack.

```bash
taxiway observe up
taxiway observe open
```

--------------------------------

### Generate shell completion

Source: https://taxiway.sh/docs/contributing/development

Generate shell completion scripts for the local development binary.

```makefile
make completion
```

--------------------------------

### List recordings for a lab

Source: https://taxiway.sh/docs/how-to/recordings

Lists all recordings associated with a specific lab.

```bash
taxiway record list mylab
```

--------------------------------

### Environment variables for local runtime

Source: https://taxiway.sh/docs/contributing/development

These variables configure the local runtime to use checkout-specific assets and isolated directories.

```bash
export TAXIWAY_CONTEXT=dev
export TAXIWAY_CONTEXT_ID="$(test -f "$PWD/.context-id" || uuidgen | tr '[:upper:]' '[:lower:]' | cut -c1-8 > "$PWD/.context-id"; cat "$PWD/.context-id")"
export TAXIWAY_AUTH_DIR="$PWD/.auth"
export TAXIWAY_OBSERVABILITY_DIR="$PWD/.observability"
export TAXIWAY_PROXY_DIR="$PWD/.proxy"
export TAXIWAY_RUNTIME_DIR="$PWD"
export TAXIWAY_LAB_STATE_DIR="$PWD/.lab-state"
```

--------------------------------

### Analyze in interactive mode

Source: https://taxiway.sh/docs/how-to/recordings

Opens the selected runner in an interactive UI with the analysis prompt loaded.

```bash
taxiway record analyze mylab --record delivery-run --interactive
```

--------------------------------

### Generate shell completion

Source: https://taxiway.sh/docs/reference/configuration

Generate completion scripts for zsh, bash, and fish shells.

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

--------------------------------

### Set environment variables for LiteLLM routing

Source: https://taxiway.sh/docs/how-to/gateway

Configure Claude Code to point Anthropic traffic at LiteLLM and forward the OAuth header. Requires a LiteLLM API key.

```bash
export ANTHROPIC_BASE_URL=http://<lab>.litellm.internal:4000
export ANTHROPIC_CUSTOM_HEADERS="x-litellm-api-key: Bearer $TAXIWAY_LITELLM_API_KEY"

```

--------------------------------

### Lab state directory

Source: https://taxiway.sh/docs/reference/configuration

Default location for lab state. Override with --state-dir <path> or TAXIWAY_LAB_STATE_DIR.

```bash
~/.taxiway/lab-state
```

--------------------------------

### Send test prompt for trace verification

Source: https://taxiway.sh/docs/how-to/gateway

Send a small prompt in the attached orchestrator session to generate a trace.

```text
Respond with only: trace-ok

```

--------------------------------

### Attach to lab session

Source: https://taxiway.sh/docs/how-to/gateway

Attaches to the lab session for Codex subscription testing.

```bash
taxiway shell <lab>
```

--------------------------------

### Analyze recordings

Source: https://taxiway.sh/docs/how-to/recordings

Analyzes stopped recordings using a local agent runner.

```bash
taxiway record analyze mylab
```

--------------------------------

### LiteLLM config to forward client headers

Source: https://taxiway.sh/docs/how-to/gateway

Required setting to forward the OAuth Authorization header to Anthropic. Without it, authentication fails.

```yaml
general_settings:
  forward_client_headers_to_llm_api: true

```

--------------------------------

### Send test prompt to Codex

Source: https://taxiway.sh/docs/how-to/gateway

Sends a small prompt in the attached Codex session to verify subscription routing.

```text
Respond with only: codex-subscription-ok
```

--------------------------------

### ref.json lab metadata file (v5, codex, lima)

Source: https://taxiway.sh/docs/reference/architecture

Persisted `ref.json` in the lab state directory. It is the source of truth for resuming commands without repeating command-line flags; the lab name sets the environment name (usually `taxiway-<lab>`), and the orchestrator type is stored separately so `taxiway run <lab>` can resume the correct adapter without another `--type` flag.

```json
{
  "version": 5,
  "lab": "mylab",
  "orch": "codex",
  "driver": "lima",
  "workspace": {
    "repo": "https://github.com/org/repo",
    "ref": "main",
    "path": "subdir"
  },
  "orchestrator_profile": {
    "name": "default"
  },
  "settings": {
    "version": "latest"
  }
}

```

--------------------------------

### Generate shell-specific completion

Source: https://taxiway.sh/docs/contributing/development

Generate completion scripts for specific shells.

```makefile
make completion-zsh
make completion-bash
make completion-fish
```

--------------------------------

### Codex model provider configuration

Source: https://taxiway.sh/docs/how-to/gateway

Configures Codex to use a custom OpenAI-compatible provider pointing to the lab LiteLLM gateway. Uses responses wire API and requires OpenAI auth.

```toml
model_provider = "taxiway-litellm"
model = "gpt-5.5"

[model_providers.taxiway-litellm]
name = "Taxiway LiteLLM"
base_url = "http://<lab>.litellm.internal:4000/v1"
wire_api = "responses"
requires_openai_auth = true
env_http_headers = { "x-litellm-api-key" = "TAXIWAY_LITELLM_API_KEY", "x-litellm-agent-id" = "TAXIWAY_LITELLM_AGENT_ID" }
supports_websockets = false
```

--------------------------------

### Exercise Docker skip path in end-to-end tests

Source: https://taxiway.sh/docs/contributing/testing

Sets `LAB_NO_DOCKER=1` to force the end-to-end tests to skip when Docker is unavailable. A skipped test is not evidence that the lifecycle works.

```shell
LAB_NO_DOCKER=1 make test-e2e-only

```

--------------------------------

### Set default driver for shell

Source: https://taxiway.sh/docs/reference/configuration

Set LAB_DRIVER environment variable to define a default driver for the shell.

```bash
export LAB_DRIVER=docker
taxiway up mylab
```

--------------------------------

### Analyze a named recording

Source: https://taxiway.sh/docs/how-to/recordings

Analyzes a specific named recording.

```bash
taxiway record analyze mylab --record delivery-run
```

--------------------------------

### Taxiway observe lifecycle commands

Source: https://taxiway.sh/docs/how-to/observability

Commands to stop, remove, or reset the Langfuse observability stack. `down` is non-destructive, `rm` removes containers and runtime state, `rm --volumes` also removes data volumes, and `reset` wipes the Postgres volume permanently deleting all traces.

```bash
taxiway observe down          # stop only; keep containers, volumes, and runtime state
taxiway observe rm            # remove containers and clear runtime state
taxiway observe rm --volumes  # also remove observability data volumes
taxiway observe reset         # rm --volumes, then restart

```
Tokens:
Raw