> ## Documentation Index
> Fetch the complete documentation index at: https://astronomer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Apache Airflow® locally

When developing [Apache Airflow®](https://airflow.apache.org/) Dags locally using AI agents, you need to give your agents a way to test their Dag changes in an Airflow environment. The easiest way for humans and AI agents alike to run Airflow on your computer is by using the [Astro CLI](/docs/cli/v1.44/overview), which gives you a fully functional Airflow environment, as well as options to test your Dag code. While the Astro CLI is freely available and you don't need to be an Astronomer customer to install and use it, you can use additional functionality if you have an Astronomer account.

<Tip>
  The Astro CLI contains the `astro otto` command, which lets you interact with Otto, Astronomer's data engineering agent. You can run Otto with models from Anthropic, OpenAI, and Google, and it's available as part of the [free Astro trial](https://www.astronomer.io/lp/signup/). See [Otto overview](/docs/astro/otto-overview) for more information.
</Tip>

<Info>
  For a hands-on demo of using AI agents in local data engineering, watch the recording of the [Local data engineering in the agentic era](https://www.astronomer.io/events/webinars/local-data-engineering-in-the-agentic-era-video/) webinar.
</Info>

## Assumed knowledge

To get the most out of this guide, you should have existing knowledge of:

* Airflow basics. See [Introduction to Apache Airflow®: A Technical Overview for Beginners](/docs/learn/intro-to-airflow).
* Basic use of a terminal. See [GNU Bash manual](https://www.gnu.org/software/bash/manual/).

## Install the Astro CLI

You can install the Astro CLI using [Homebrew](https://formulae.brew.sh/formula/astro) or directly with `curl`.

```bash theme={null}
curl -sSL install.astronomer.io | sudo bash -s
```

If you installed the Astro CLI previously, rerun the install command to upgrade to the latest version and access all commands mentioned in this document.

## Create and start an Airflow project

Use the `astro dev init` command to create a full Airflow project, including an example Dag, in any empty folder on your computer. Start the project with `astro dev start` in one of two modes.

```bash theme={null}
astro dev init                # create a new Airflow project in the current folder
astro dev start               # start Airflow (container mode by default, --standalone for standalone mode)
```

Container mode runs Airflow in five containers, one for each core component (Docker or Podman required):

* **Scheduler**: Monitors Dags and task instances, and schedules a task to run as soon as its dependencies are fulfilled, using the `LocalExecutor`, which runs tasks inside the scheduler process itself. This is the container you want to use as a dev container when developing Airflow Dags. See [Set up your IDE for data engineering](/docs/learn/set-up-your-ide-for-data-engineering).
* **API server**: A FastAPI server that serves the Airflow UI and the [Airflow REST API](https://airflow.apache.org/docs/apache-airflow/stable/stable-rest-api-ref.html). It also allows workers to interact with the metadata database through an internal API.
* **Dag processor**: Parses the Dag files in your project and stores a serialized version of each Dag in the metadata database.
* **Metadata database**: Stores operational information for Airflow, such as serialized Dags and the history of Dag runs and task instances. The Astro CLI in container mode uses Postgres for this database.
* **Triggerer**: Runs asynchronous triggers for [deferrable operators](/docs/learn/deferrable-operators) and [event-driven scheduling](/docs/learn/airflow-event-driven-scheduling).

See [Apache Airflow components](/docs/learn/airflow-components) for how these components interact with each other.

<Info>
  You can still write Airflow Dags even if you can't install the Astro CLI on your computer. Astro includes the [Astro IDE](/docs/astro/ide-overview), an in-browser Airflow development environment, where you can write Dags (with optional assistance from Otto), push them to a test Deployment, and commit them to a Git repository. The Astro IDE is included in every [free Astro trial](https://www.astronomer.io/lp/signup/).
</Info>

### Container mode vs standalone mode

|                   | Container mode (default)                | Standalone mode (experimental)            |
| ----------------- | --------------------------------------- | ----------------------------------------- |
| Requires          | Docker or Podman                        | -                                         |
| Runs Airflow as   | Five containers, one per core component | Processes in a Python virtual environment |
| Start project     | `astro dev start`                       | `astro dev start --standalone`            |
| Executor          | `LocalExecutor`                         | `LocalExecutor`                           |
| Metadata database | Postgres                                | SQLite                                    |

The Airflow UI is where you view Dag runs, trigger Dags manually, and inspect task logs. By default, `astro dev start` runs a built-in reverse proxy that serves the Airflow UI at `<project>.localhost:6563`, based on your project folder name. This applies in both container mode and standalone mode, and lets you run multiple Airflow projects at the same time without manually managing ports. Use `astro dev start --no-proxy` to serve the Airflow UI directly at `localhost:8080` instead. See [`astro dev proxy`](/docs/cli/v1.44/astro-dev-proxy) for more information.

The first Airflow project you start is still available at `localhost:8080` even with the proxy enabled. If you start an additional project while the first one is still running, that project gets a random port instead and is only reachable through its own `<project>.localhost:6563` address.

See [Standalone mode](/docs/cli/v1.44/astro-dev-start#standalone-mode) in the `astro dev start` reference for more information.

Astronomer recommends container mode unless you can't run Docker or Podman.

## Astro CLI commands for local development

The Astro CLI has many commands for your AI agent (and you) to interact with your Airflow environments that run locally and on Astro. The following commands are especially useful when working locally:

```bash theme={null}
astro completion <shell>         # tab completions for Astro CLI commands
astro api airflow                # query the Airflow Registry API
astro dev bash                   # exec into the scheduler container
astro dev kill                   # remove all containers, metadata database, connections
astro dev logs                   # component logs: -s scheduler, -t triggerer,
                                 # --api-server, --dag-processor, -f to follow
astro dev parse                  # check for Dag import errors
astro dev pytest                 # run tests in /tests inside a container
astro dev run                    # run any Airflow CLI command
astro dev run dags reserialize   # force re-parse of all Dags, including new ones
```

The `astro dev run` command can run any [Airflow CLI](https://airflow.apache.org/docs/apache-airflow/stable/cli-and-env-variables-ref.html) command. Replace `airflow` with `astro dev run`.

If you have an Astro account, you have access to many more commands that interact with Deployments on Astro. Otto, Astronomer's data engineering AI agent, uses a large language model (LLM) gateway running on Astro, which is why you need to sign in to work with Otto.

```bash theme={null}
astro login   # sign in to your Astro account
astro otto    # launch Otto, Astronomer's data engineering agent
astro deploy  # push your local project to an Astro Deployment

# start locally with the same connections you configured in the 
# Astro Environment Manager for a Deployment
astro dev start --deployment-id <deployment-id>
```

## Restrict agent commands

Most AI coding agents can call the command-line tools already installed on your computer. If you allow your harness to run Bash commands without human approval, for example in Claude Code's auto mode, where a classifier by Anthropic decides whether a command appears to be safe, your agent can run CLI commands that have unintended consequences.

Agent harnesses typically offer you a way to give more fine-grained permissions for specific CLI commands. [Claude Code](https://code.claude.com/docs/en/permissions), for example, defines command permissions in `settings.json` under a `permissions` object with three lists:

* `allow`: Commands Claude Code runs without asking
* `deny`: Commands Claude Code never runs, even if a broader `allow` rule matches
* `ask`: Commands Claude Code confirms with you before running

A `deny` rule always overrides a matching `allow` rule.

For example, this configuration lets Claude Code run any `astro dev` sub-command without asking, but requires confirmation before it runs `astro deploy`:

```json theme={null}
{
  "permissions": {
    "allow": [
      "Bash(astro dev *)"
    ],
    "ask": [
      "Bash(astro deploy *)"
    ]
  }
}
```

Any commands that don't match a rule use the current general setting, for example asking for permission if the harness is in manual mode and potentially running without asking for approval if the harness is in auto mode.

<Note>
  This example is for Claude Code. If you're using another harness such as [OpenAI Codex](https://openai.com/codex/) or [Google Gemini CLI](https://geminicli.com/), you have different options to restrict CLI command usage. See the relevant harness documentation for more information.
</Note>