Managing Astro Local Env

by astronomercbe1141f547bNo license451 starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated today

Manage local Airflow environment with Astro CLI (Docker and standalone modes). Use when the user wants to start, stop, or restart Airflow, view logs, query the Airflow API, troubleshoot, or fix environment issues. For project setup, see setting-up-astro-project.

Instructions onlyDevOps & Cloud
AI-generated overview

Manage a local Airflow environment with the Astro CLI: start, stop, restart, logs, API queries and troubleshooting.

What it does
This skill provides instructions for operating a local Airflow environment through the Astro CLI in Docker or standalone mode. It covers starting, stopping, restarting and killing environments, checking status, viewing logs, running Airflow CLI commands, and querying the Airflow API for DAGs, DAG runs, task instances, connections, variables and config. It also includes troubleshooting and reset guidance, reverse proxy configuration, and Airflow version upgrade steps. It is instructions only and ships no scripts.
When to use it
Use it when a user wants to start, stop or restart local Airflow, inspect logs or status, query the local Airflow API, or diagnose and fix local environment problems. It is not intended for initial project setup, which it points to a separate skill.
Requirements
The Astro CLI, Docker for the default mode, and for standalone mode Airflow 3 runtime plus uv on PATH (not supported on Windows). Local network access to the Airflow webserver and API; default credentials admin/admin. No scripts are included.

Astro Local Environment

This skill helps you manage your local Airflow environment using the Astro CLI.

Two modes: Docker (default, uses containers) and Standalone (Docker-free, uses a local venv — requires Airflow 3 + uv).

To set up a new project, see the setting-up-astro-project skill. When Airflow is running, use MCP tools from authoring-dags and testing-dags skills.

Start / Stop / Restart (Docker)

bash
# Start local Airflow (webserver at http://localhost:8080)astro dev start
# Stop containers (preserves data)astro dev stop
# Kill and remove volumes (clean slate)astro dev kill
# Restart all containersastro dev restart
# Restart specific componentastro dev restart --schedulerastro dev restart --webserver

Default credentials: admin / admin

Restart after modifying: requirements.txt, packages.txt, Dockerfile

Standalone mode? See the next section.

Standalone Mode

Docker-free local development. Runs Airflow directly on your machine in a .venv/ managed by uv.

Requirements: Airflow 3 (runtime 3.x), uv on PATH. Not supported on Windows.

Plain astro dev init already pins a runtime 3.x image, so no version flag is needed. See setting-up-astro-project for project initialization.

Start

bash
# One-time: set standalone as default modeastro config set dev.mode standalone
# Or use the flag per invocationastro dev start --standalone
FlagDescription
--foreground / -fStream output in foreground
--port / -pOverride webserver port (default: 8080)
--no-proxyDisable reverse proxy

Stop / Kill / Restart

bash
# Stop (preserves .venv)astro dev stop
# Kill (removes .venv and .astro/standalone/ — clean slate)astro dev kill
# Restart (preserves .venv for fast restart, use -k to kill first)astro dev restart

If you used --standalone on start instead of setting the config, pass --standalone on every subsequent command too (stop, kill, restart, bash, run, logs, etc.).

State locations: venv in .venv/, database and logs in .astro/standalone/, DAGs from dags/.

Reverse Proxy

Run multiple Airflow projects locally without port conflicts. Works in both Docker and standalone modes.

Each project gets a hostname like <project-name>.localhost:6563. Visit http://localhost:6563 to see all active projects.

bash
# Check proxy status and active routesastro dev proxy status
# Force-stop proxy (auto-restarts on next astro dev start)astro dev proxy stop
ConfigCommand
Change proxy portastro config set proxy.port <port>
Disable per-startastro dev start --no-proxy

Default proxy port: 6563

Check Status

bash
astro dev ps

View Logs

bash
# All logsastro dev logs
# Specific componentastro dev logs --schedulerastro dev logs --webserver
# Follow in real-timeastro dev logs -f

Standalone: astro dev logs works the same but shows a unified log (no per-component filtering).

Run Airflow CLI Commands

bash
# Open a shell with Airflow environmentastro dev bash
# Run Airflow CLI commandsastro dev run airflow infoastro dev run airflow dags list

Standalone: Same commands work — bash opens a venv-activated shell, run executes in the venv.

Querying the Airflow API

Use astro api airflow to query a running local Airflow instance. Prefer operation IDs over URL paths.

Defaults: localhost:8080, admin/admin (auto-detected). Override with --api-url, --username, --password.

Discovery

bash
# List all endpointsastro api airflow ls
# Filter by keywordastro api airflow ls dagsastro api airflow ls task
# Show params and schema for an operationastro api airflow describe get_dag

Key Flags

FlagPurpose
-p key=valuePath parameters
-F key=valueBody/query fields (auto-converts booleans/numbers)
-q / --jqjq filter on response
--paginateFetch all pages
-X / --methodOverride HTTP method
--generateOutput curl command instead of executing

DAGs

bash
# List all DAGsastro api airflow get_dags
# Filter by pattern (SQL LIKE — use % wildcards)astro api airflow get_dags -F dag_id_pattern=%etl%
# Get a specific DAGastro api airflow get_dag -p dag_id=my_dag
# Get full details (schedule, params, etc.)astro api airflow get_dag_details -p dag_id=my_dag
# Pause / unpauseastro api airflow patch_dag -p dag_id=my_dag -F is_paused=trueastro api airflow patch_dag -p dag_id=my_dag -F is_paused=false
# View DAG source codeastro api airflow get_dag_source -p dag_id=my_dag
# Check import errorsastro api airflow get_import_errors

DAG Runs

bash
# List runs for a DAGastro api airflow get_dag_runs -p dag_id=my_dag
# Trigger a runastro api airflow trigger_dag_run -p dag_id=my_dag
# Trigger with configastro api airflow trigger_dag_run -p dag_id=my_dag -F conf[key]=value
# Get a specific runastro api airflow get_dag_run -p dag_id=my_dag -p dag_run_id=manual__2026-04-07
# Clear (re-run) a DAG runastro api airflow clear_dag_run -p dag_id=my_dag -p dag_run_id=manual__2026-04-07 -F dry_run=false

Task Instances

bash
# List task instances for a runastro api airflow get_task_instances -p dag_id=my_dag -p dag_run_id=manual__2026-04-07
# Use ~ as wildcard (all DAGs or all runs)astro api airflow get_task_instances -p dag_id=my_dag -p dag_run_id=~
# Get a specific task instanceastro api airflow get_task_instance -p dag_id=my_dag -p dag_run_id=manual__2026-04-07 -p task_id=extract
# Clear/retry failed tasksastro api airflow post_clear_task_instances -p dag_id=my_dag \  -F dag_run_id=manual__2026-04-07 -F only_failed=true -F dry_run=false
# Get task logsastro api airflow get_log -p dag_id=my_dag -p dag_run_id=manual__2026-04-07 \  -p task_id=extract -p try_number=1

Config & Connections

bash
astro api airflow get_connectionsastro api airflow get_variablesastro api airflow get_config

Filtering with jq

bash
# List only DAG IDsastro api airflow get_dags -q '.dags[].dag_id'
# Get failed task IDs from a runastro api airflow get_task_instances -p dag_id=my_dag -p dag_run_id=~ \  -q '[.task_instances[] | select(.state=="failed") | .task_id]'

Troubleshooting

IssueSolution
Port 8080 in useStop other containers or edit .astro/config.yaml
Container won't startastro dev kill then astro dev start
Package install failedCheck requirements.txt syntax
DAG not appearingRun astro dev parse to check for import errors
Out of disk spacedocker system prune
Standalone won't startEnsure uv is on PATH and runtime is 3.x
Proxy port conflictastro config set proxy.port <port>
.venv corruptedastro dev kill then astro dev start --standalone

Reset Environment

When things are broken:

bash
astro dev killastro dev start

Upgrade Airflow

Test compatibility first

bash
astro dev upgrade-test

Change version

  1. Edit Dockerfile:

    dockerfile
    FROM quay.io/astronomer/astro-runtime:13.0.0

  2. Restart:

    bash
    astro dev kill && astro dev start

Related Skills

  • setting-up-astro-project: Initialize projects and configure dependencies
  • authoring-dags: Write DAGs (uses MCP tools, requires running Airflow)
  • testing-dags: Test DAGs (uses MCP tools, requires running Airflow)
  • deploying-airflow: Deploy DAGs to production (Astro, Docker Compose, Kubernetes)

Source and attribution

Source:astronomer/agentsinskills/managing-astro-local-envat commitcbe1141

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

More from astronomer/agents

Warehouse Init

astronomer

Discovers data warehouse schema metadata and generates a shareable .astro/warehouse.md reference file for fast concept-to-table lookups.

Data & Analytics451updated today

Tracing Upstream Lineage

astronomer

Trace upstream data lineage. Use when the user asks where data comes from, what feeds a table, upstream dependencies, data sources, or needs to understand data origins.

Awaiting classification451updated today

Tracing Downstream Lineage

astronomer

Traces downstream data lineage to assess what breaks when a table or DAG changes.

Data & Analytics451updated today

Testing Dags

astronomer

Guides iterative testing, debugging and fixing of Airflow DAGs using af CLI commands.

Software Development451updated today

Setting Up Astro Project

astronomer

Initializes and configures Astro/Airflow projects with the Astro CLI, covering dependencies, connections, and variables.

DevOps & Cloud451updated today

Profiling Tables

astronomer

Profiles a database table with SQL statistics, cardinality, samples and a data quality assessment.

Data & Analytics451updated today

More in DevOps & Cloud

Amazon Location Service

awslabs

Guides integration of Amazon Location Service APIs for maps, geocoding, routing, places search, geofencing and tracking.

DevOps & Cloud915updated today

Managing Astro Deployments

astronomer

Guides use of the Astro CLI to authenticate, manage workspaces, and create, update, delete, and deploy Astronomer production deployments.

DevOps & Cloud451updated today

Deploying Airflow

astronomer

Guides deploying Airflow DAGs and projects to production via Astro, Docker Compose, or Kubernetes Helm.

DevOps & Cloud451updated today

Airflow State Store

astronomer

Guides Airflow 3.3 task and asset state stores, crash-safe resumable job submission, and submit-and-poll DAG review.

DevOps & Cloud451updated today

Airflow

astronomer

Operates and troubleshoots Apache Airflow instances through the af CLI, covering DAGs, runs, tasks, logs, config and health.

Includes scripts
DevOps & Cloud451updated today

Monitor Reliability

amplitude

Produces a proactive product reliability health check from Amplitude error, network, and error-click data.

DevOps & Cloud42updated today