# Overwire > Overwire is a local workflow workbench: run, mock, and debug your GitHub Actions workflow files locally. These docs cover the desktop app, the scriptable CLI, and the flat .overwire/ configuration model. JSON Schemas for every .overwire/ config format: https://docs.overwire.io/schemas/index.json Demo workspace: https://github.com/overwire/demo — agent guide: run `overwire agents`. ## Overview - [Overwire](https://docs.overwire.io/): Run, mock, and debug your GitHub Actions workflow files locally with Overwire, a local workflow workbench. ## Getting started - [Installation](https://docs.overwire.io/getting-started/installation/): Install the Overwire desktop app and CLI. - [Initialize a project](https://docs.overwire.io/getting-started/initialize/): Scaffold the .overwire/ config tree with overwire init. - [First mock run](https://docs.overwire.io/getting-started/first-mock-run/): Execute a workflow locally with every step mocked. No container engine required. - [First live run](https://docs.overwire.io/getting-started/first-live-run/): Execute workflow steps for real inside the Overwire runner container. - [Demo workspace](https://docs.overwire.io/getting-started/demo/): Ready-made demo workspaces that exercise every Overwire feature. Clone and explore. ## Concepts - [Step modes](https://docs.overwire.io/concepts/modes/): Every step has a mode, skip, mock, or live. Modes live in sidecar config, never in your workflow YAML. - [Workspaces and instances](https://docs.overwire.io/concepts/workspaces/): How Overwire models repositories, owners, and multi-repo workspaces. - [The config root](https://docs.overwire.io/concepts/config-root/): The flat .overwire/ directory is the source of truth for everything Overwire knows about a repository. - [Mock contracts](https://docs.overwire.io/concepts/mock-contracts/): YAML sidecars that declare expected inputs and synthesized outputs for mocked actions. - [Action support tiers](https://docs.overwire.io/concepts/support-tiers/): How Overwire satisfies a uses reference, native, live, mock, or unsupported. - [Runs and the run store](https://docs.overwire.io/concepts/runs/): Every run persists as a self-contained record you can inspect, compare, and re-run from. - [Licensing and purchases](https://docs.overwire.io/concepts/licensing/): What is free, what Pro covers, how activation works, and how purchases and refunds are handled. ## CLI reference - [CLI overview](https://docs.overwire.io/cli/): The overwire command line, every command at a glance. - [overwire init](https://docs.overwire.io/cli/init/): Scaffold a flat .overwire/ config tree. - [overwire doctor](https://docs.overwire.io/cli/doctor/): Health-check Node, the container engine, and the .overwire config tree. - [overwire parse](https://docs.overwire.io/cli/parse/): Parse a workflow YAML file and print its structure. - [overwire list](https://docs.overwire.io/cli/list/): List workflows with their triggers and jobs. - [overwire lint](https://docs.overwire.io/cli/lint/): Lint a workflow file for common issues. - [overwire explain](https://docs.overwire.io/cli/explain/): Explain how Overwire would support a workflow without running it. - [overwire simulate](https://docs.overwire.io/cli/simulate/): Print a simulated event payload, optionally wrapped in a full github context. - [overwire run](https://docs.overwire.io/cli/run/): Execute a workflow locally. Mock by default, live in a container with --docker. - [overwire chain](https://docs.overwire.io/cli/chain/): Run or inspect workflow-chain scenario sessions. - [overwire resolve](https://docs.overwire.io/cli/resolve/): Fetch and parse an action's action.yml; optionally print a mock contract. - [overwire seed-mocks](https://docs.overwire.io/cli/seed-mocks/): Write a mock contract for every uses: step in a workflow. - [overwire status](https://docs.overwire.io/cli/status/): Show latest workflow and check status for a repository ref or SHA. - [overwire history](https://docs.overwire.io/cli/history/): List recent workflow runs from the run store. - [overwire cache](https://docs.overwire.io/cli/cache/): Inspect or clear the action cache and the persisted tool cache. - [overwire validate](https://docs.overwire.io/cli/validate/): Validate every workflow and config file in the project without running anything. - [overwire schema](https://docs.overwire.io/cli/schema/): Print the JSON Schema for any .overwire/ config file format. - [overwire agents](https://docs.overwire.io/cli/agents/): Print the guide for AI agents driving Overwire. - [overwire license](https://docs.overwire.io/cli/license/): Manage the Overwire Pro license shared with the desktop app. ## Configuration reference - [Configuration overview](https://docs.overwire.io/configuration/): Every file in the .overwire/ config root and what it does. - [settings.yml](https://docs.overwire.io/configuration/settings/): Repository owner and Overwire settings. - [variables.yml](https://docs.overwire.io/configuration/variables/): Repository variables resolved by vars.* expressions. - [secrets.yml](https://docs.overwire.io/configuration/secrets/): Secret declarations, optionally with local-only values. - [modes/](https://docs.overwire.io/configuration/modes/): Workflow default mode and per-job, per-step overrides. - [mocks/](https://docs.overwire.io/configuration/mocks/): Mock contracts for uses: steps. - [payloads/ and dispatch/](https://docs.overwire.io/configuration/payloads/): Saved event payload overrides and workflow_dispatch input defaults. - [rulesets.json](https://docs.overwire.io/configuration/governance/): Branch rulesets in GitHub's native export format. - [pull-requests.yml and statuses.yml](https://docs.overwire.io/configuration/scenarios/): Local PR scenarios and external commit statuses or check runs. - [chains/](https://docs.overwire.io/configuration/chains/): Workflow chain scenarios: ordered multi-workflow sessions run as one unit. - [custom-properties.yml](https://docs.overwire.io/configuration/custom-properties/): Repository custom properties that surface in event payloads. - [api-mocks.yml](https://docs.overwire.io/configuration/api-mocks/): Declarative GitHub API mock routes with capture and suggest. - [environments/](https://docs.overwire.io/configuration/environments/): Per-environment variables, secrets, and protection rules. - [instances.yml](https://docs.overwire.io/configuration/instances/): The workspace peer list for multi-repo workspaces. - [state/ and cache/](https://docs.overwire.io/configuration/state-and-cache/): Run-derived state and the local workflow cache. Local-only. ## App guide - [The workbench](https://docs.overwire.io/app/workbench/): The workbench page is the main view: a filterable workflow list, the interactive DAG canvas, and a detail panel. - [The runs panel](https://docs.overwire.io/app/runs-panel/): The bottom panel follows a run from configuration to summary across four tabs: Support plan, Trigger event, Workflow run, and Run summary. - [Editors](https://docs.overwire.io/app/editors/): The explorer page opens workflow and config files in tabbed editors with inline lint diagnostics and mode controls. - [Pull requests](https://docs.overwire.io/app/pull-requests/): The pull requests page evaluates local PR scenarios against rulesets and required checks to predict the merge outcome. - [Repository settings](https://docs.overwire.io/app/repository/): The repository page edits per-repo platform state: organization, variables, secrets, environments, custom properties, rulesets, and statuses. - [The runner page](https://docs.overwire.io/app/runner/): The runner page manages the container engine connection and the Overwire runner image. - [Settings](https://docs.overwire.io/app/settings/): Application settings cover appearance, secret storage, privacy, and support tooling. - [Keyboard shortcuts](https://docs.overwire.io/app/shortcuts/): Every keyboard shortcut in the Overwire desktop app. ## Automation - [Automate Overwire with AI agents](https://docs.overwire.io/automation/ai-agents/): Drive Overwire from AI coding agents: files are the API, the CLI is the executor. ## Platform - [Directory layout](https://docs.overwire.io/platform/directory-layout/): Where Overwire reads and writes on your machine, and what is safe to delete. - [Uninstall & reset](https://docs.overwire.io/platform/uninstall/): Remove Overwire completely, or reset local state without uninstalling. - [Privacy & data handling](https://docs.overwire.io/platform/privacy/): What runs locally, what can leave your machine, and how to turn each channel off. - [Changelog](https://docs.overwire.io/platform/changelog/): What shipped in each Overwire release. ## Troubleshooting - [Troubleshooting](https://docs.overwire.io/troubleshooting/): Diagnose environment problems with doctor, decode every Overwire error class, and share a redacted diagnostic bundle. - [FAQ](https://docs.overwire.io/troubleshooting/faq/): Frequently asked questions about Overwire. ## Optional - [Full documentation as one file](https://docs.overwire.io/llms-full.txt) Overwire is not affiliated with, endorsed by, or sponsored by GitHub, Inc. "GitHub" and "GitHub Actions" are trademarks of GitHub, Inc.