For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
      • AstroFully-managed data operations, powered by Apache Airflow.
      • Astro Private CloudRun Airflow-as-a-service in your environment.
      • Professional ServicesExpert Airflow services for your enterprise's success.
    • Tools
      • Cosmos
      • Orbiter
      • CLI
      • AI SDK
      • Agents
      • Blueprint
      • UpdatesThe State of Airflow 2026See the insights from over 5,800 data practitioners in the full report. Download Now ➔
  • Customers
  • Docs
    • Insights
      • Blog
      • Webinars
      • Resource Library
      • Events
    • Education
      • Academy
      • What is Airflow?
  • Pricing
Get Started Free
    • Astro CLI
    • Quickstart
    • CLI reference
      • astro completion
      • astro api
      • astro auth
      • astro config
      • astro context
      • astro dbt
      • astro deploy
      • astro deployment
      • astro dev
        • astro dev bash
        • astro dev build
        • astro dev init
        • astro dev kill
        • astro dev logs
        • astro dev object export
        • astro dev object import
        • astro dev parse
        • astro dev proxy
        • astro dev ps
        • astro dev pytest
        • astro dev restart
        • astro dev run
        • astro dev start
        • astro dev stop
        • astro dev upgrade-test
      • astro ide
      • astro login
      • astro logout
      • astro organization
      • astro otto
      • astro remote
      • astro run
      • astro team
      • astro telemetry
      • astro user create
      • astro version
      • astro workspace

Product

  • Platform Overview
  • Astro
  • Astro Observe
  • Astro Private Cloud
  • Security & Trust
  • Pricing

Tools & Services

  • Cosmos
  • Docs
  • Professional Services
  • Product Updates

Use Cases

  • AI Ops
  • Data Observability
  • ETL/ELT
  • ML Ops
  • Operational Analytics
  • All Use Cases

Industries

  • Financial Services
  • Gaming
  • Retail
  • Manufacturing
  • Healthcare
  • All Industries

Resources

  • Academy
  • eBooks & Guides
  • Blog
  • Webinars
  • Events
  • The Data Flowcast Podcast
  • All Resources

Airflow

  • What is Airflow
  • Airflow on Astro
  • Airflow 3.0
  • Airflow Upgrades
  • Airflow Use Cases
  • Airflow 2.x End of Life

Company

  • Our Story
  • Customers
  • Newsroom
  • Careers
  • Contact

Support

  • Knowledge Base
  • Status
  • Contact Support
GitHubYouTubeLinkedInx
  • Legal
  • Privacy
  • Terms of Service
  • Consent Preferences

  • Do Not Sell or Share My Personal information
  • Limit the Use Of My Sensitive Personal Information

Apache Airflow®, Airflow, and the Airflow logo are trademarks of the Apache Software Foundation. Copyright © Astronomer 2026. All rights reserved.

LogoLogo
CLI referenceastro dev

astro dev start

Edit this page
Built with
The behavior and format of this command are the same for both Astro and Astro Private Cloud.

Start a local Airflow environment in Docker mode (default) or standalone mode (without Docker).

For more information, see Build and run a project locally.

Usage

1astro dev start

Options

OptionDescriptionPossible Values
--build-secretsRun docker build --secret to mount a secret value to your Docker image. Docker mode only.id=<your-secret-id>, src=<path-to-secret> . See Docker documentation.
--compose-fileThe location of a custom Docker Compose file to use for starting Airflow on Docker. Docker mode only.Any valid filepath
--deployment-idSpecifies a Deployment whose Environment Manager configurations you want to use locally. When Airflow builds locally, Astro populates the Airflow metadata database with the Airflow objects specified from the Deployment Environment Manager in the Astro UI. Local development access to connections must be enabled first. See Use Airflow connections hosted on Astro in a local environment.Any valid Deployment ID
--dockerRun in Docker mode. Use to override the dev.mode project config for a single command.None
-e,--envPath to your environment variable file. Default is .envValid filepaths
-f, --foregroundRun Airflow in the foreground instead of as a background process. Standalone mode only.None
-i, --image-nameThe name of a pre-built custom Docker image to use with your project. The image must be available on your local machine. Docker mode only.A valid name for a pre-built Docker image based on Astro Runtime
-n, --no-browserStarts a local Airflow environment without opening a web browser for the Airflow UI. Docker mode only.None
--no-cacheDo not use cache when building your Astro project into a Docker image. Docker mode only.None
--no-proxyDisable the built-in reverse proxy and use classic fixed-port behavior.None
-p, --portPort for the Airflow API server. Standalone mode only.Any valid port number
-s, --settings-fileSettings file from which to import Airflow objects. Default is airflow_settings.yaml.Any valid path to an Airflow settings file
--standaloneRun in standalone mode without Docker. Use to override the dev.mode project config for a single command. See Standalone mode.None
--waitAmount of time to wait for the webserver to get healthy before timing out. The default is 1 minute for most machines and 5 minutes for Apple M1 machines.Time in minutes defined as <integer>m and time in seconds defined as <integer>s
-workspace-idSpecifies a Workspace whose Environment Manager configurations you want to use locally. When Airflow builds locally, Astro populates the Airflow metadata database with the Airflow objects to all Deployments in the Workspace.Any valid Workspace ID

Examples

1$ astro dev start --env=/users/username/documents/myfile.env

The following error can sometimes occur when the CLI tries to build your Astro Runtime image using Podman:

$WARN[0010] SHELL is not supported for OCI image format, [/bin/bash -o pipefail -e -u -x -c] will be ignored. Must use `docker` format

You can resolve this issue by exporting the BUILDAH_FORMAT environment variable to Podman:

1export BUILDAH_FORMAT=docker

Standalone mode

Standalone mode runs Airflow directly on your machine in a virtual environment, without Docker. Use it when Docker isn’t available or when you want a lighter-weight local setup.

To set standalone as the default mode for a project:

$astro config set dev.mode standalone

To use standalone mode for a single command:

$astro dev start --standalone

To switch back to Docker mode:

$astro config set dev.mode docker

The following commands are not available in standalone mode:

  • astro dev build
  • astro dev upgrade-test
  • astro dev compose-export

astro dev run --standalone is not supported. To run Airflow CLI commands in standalone mode, set standalone as the default mode first:

$astro config set dev.mode standalone
$astro dev run dags list

Related Commands

  • astro dev restart
  • astro dev stop
  • astro dev kill
  • astro dev init
  • astro dev run
  • astro dev logs