Managing Astro Local Env Agent Skill
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.
Install
one command, takes just this skill from the repositorynpx skills add https://github.com/astronomer/agents --skill managing-astro-local-envWhat it tells the agent to use
found in the instruction textThe instruction itself
23 sections, as written by the authorAstro 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)
# 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 containers
astro dev restart
# Restart specific component
astro dev restart --scheduler
astro 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
# One-time: set standalone as default mode
astro config set dev.mode standalone
# Or use the flag per invocation
astro dev start --standalone
| Flag | Description |
|------|-------------|
| --foreground / -f | Stream output in foreground |
| --port / -p | Override webserver port (default: 8080) |
| --no-proxy | Disable reverse proxy |
Stop / Kill / Restart
# 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.
# Check proxy status and active routes
astro dev proxy status
# Force-stop proxy (auto-restarts on next astro dev start)
astro dev proxy stop
| Config | Command |
|--------|---------|
| Change proxy port | astro config set proxy.port <port> |
| Disable per-start | astro dev start --no-proxy |
Default proxy port: 6563
Check Status
astro dev ps
View Logs
# All logs
astro dev logs
# Specific component
astro dev logs --scheduler
astro dev logs --webserver
# Follow in real-time
astro dev logs -f
Standalone: astro dev logs works the same but shows a unified log (no per-component filtering).
Run Airflow CLI Commands
# Open a shell with Airflow environment
astro dev bash
# Run Airflow CLI commands
astro dev run airflow info
astro 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
# List all endpoints
astro api airflow ls
# Filter by keyword
astro api airflow ls dags
astro api airflow ls task
# Show params and schema for an operation
astro api airflow describe get_dag
Key Flags
| Flag | Purpose |
|------|---------|
| -p key=value | Path parameters |
| -F key=value | Body/query fields (auto-converts booleans/numbers) |
| -q / --jq | jq filter on response |
| --paginate | Fetch all pages |
| -X / --method | Override HTTP method |
| --generate | Output curl command instead of executing |
DAGs
# List all DAGs
astro api airflow get_dags
# Filter by pattern (SQL LIKE — use % wildcards)
astro api airflow get_dags -F dag_id_pattern=%etl%
# Get a specific DAG
astro 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 / unpause
astro api airflow patch_dag -p dag_id=my_dag -F is_paused=true
astro api airflow patch_dag -p dag_id=my_dag -F is_paused=false
# View DAG source code
astro api airflow get_dag_source -p dag_id=my_dag
# Check import errors
astro api airflow get_import_errors
DAG Runs
# List runs for a DAG
astro api airflow get_dag_runs -p dag_id=my_dag
# Trigger a run
astro api airflow trigger_dag_run -p dag_id=my_dag
# Trigger with config
astro api airflow trigger_dag_run -p dag_id=my_dag -F conf[key]=value
# Get a specific run
astro api airflow get_dag_run -p dag_id=my_dag -p dag_run_id=manual__2026-04-07
# Clear (re-run) a DAG run
astro api airflow clear_dag_run -p dag_id=my_dag -p dag_run_id=manual__2026-04-07 -F dry_run=false
Task Instances
# List task instances for a run
astro 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 instance
astro 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 tasks
astro 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 logs
astro 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
astro api airflow get_connections
astro api airflow get_variables
astro api airflow get_config
Filtering with jq
# List only DAG IDs
astro api airflow get_dags -q '.dags[].dag_id'
# Get failed task IDs from a run
astro api airflow get_task_instances -p dag_id=my_dag -p dag_run_id=~ \
-q '[.task_instances[] | select(.state=="failed") | .task_id]'
Troubleshooting
| Issue | Solution |
|-------|----------|
| Port 8080 in use | Stop other containers or edit .astro/config.yaml |
| Container won't start | astro dev kill then astro dev start |
| Package install failed | Check requirements.txt syntax |
| DAG not appearing | Run astro dev parse to check for import errors |
| Out of disk space | docker system prune |
| Standalone won't start | Ensure uv is on PATH and runtime is 3.x |
| Proxy port conflict | astro config set proxy.port <port> |
| .venv corrupted | astro dev kill then astro dev start --standalone |
Reset Environment
When things are broken:
astro dev kill
astro dev start
Upgrade Airflow
Test compatibility first
astro dev upgrade-test
Change version
- Edit
Dockerfile:
FROM quay.io/astronomer/astro-runtime:13.0.0
- Restart:
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)
Other skills for the same job
different authors, same section of the catalogue
Assess Kubernetes workloads and cluster configuration for AKS Automatic compatibility. Identifies incompatibilities, generates fixes, and guides migration from AKS Standard to AKS Automatic. WHEN: migrate to AKS Automatic, check AKS Automatic readiness, validate manifests for Automatic, assess cluster for Automatic compatibility, fix deployment for Automatic compatibility, identify AKS Automatic migration blockers, is my cluster ready for AKS Automatic.
Discovers available Azure OpenAI model capacity across regions and projects. Analyzes quota limits, compares availability, and recommends optimal deployment locations based on capacity requirements. USE FOR: find capacity, check quota, where can I deploy, capacity discovery, best region for capacity, multi-project capacity search, quota analysis, model availability, region comparison, check TPM availability. DO NOT USE FOR: actual deployment (hand off to preset or customize after discovery), quota increase requests (direct user to Azure Portal), listing existing deployments.
Interactive guided deployment flow for Azure OpenAI models with full customization control. Step-by-step selection of model version, SKU (GlobalStandard/Standard/ProvisionedManaged), capacity, RAI policy (content filter), and advanced options (dynamic quota, priority processing, spillover). USE FOR: custom deployment, customize model deployment, choose version, select SKU, set capacity, configure content filter, RAI policy, deployment options, detailed deployment, advanced deployment, PTU deployment, provisioned throughput. DO NOT USE FOR: quick deployment to optimal region (use preset).
Unified Azure OpenAI model deployment skill with intelligent intent-based routing. Handles quick preset deployments, fully customized deployments (version/SKU/capacity/RAI policy), and capacity discovery across regions and projects. USE FOR: deploy model, deploy gpt, create deployment, model deployment, deploy openai model, set up model, provision model, find capacity, check model availability, where can I deploy, best region for model, capacity analysis. DO NOT USE FOR: listing existing deployments (use foundry_models_deployments_list MCP tool), deleting deployments, agent creation (use agent/create), project creation (use project/create).
Intelligently deploys Azure OpenAI models to optimal regions by analyzing capacity across all available regions. Automatically checks current region first and shows alternatives if needed. USE FOR: quick deployment, optimal region, best region, automatic region selection, fast setup, multi-region capacity check, high availability deployment, deploy to best location. DO NOT USE FOR: custom SKU selection (use customize), specific version selection (use customize), custom capacity configuration (use customize), PTU deployments (use customize).
This skill should be used when working with LaminDB, an open-source data framework for biology that makes data queryable, traceable, reproducible, and FAIR. Use when managing biological datasets (scRNA-seq, spatial, flow cytometry, etc.), tracking computational workflows, curating and validating data with biological ontologies, building data lakehouses, or ensuring data lineage and reproducibility in biological research. Covers data management, annotation, ontologies (genes, cell types, diseases, tissues), schema validation, integrations with workflow managers (Nextflow, Snakemake) and MLOps platforms (W&B, MLflow), and deployment strategies.
Latch platform for bioinformatics workflows. Build pipelines with Latch SDK, @workflow/@task decorators, deploy serverless workflows, LatchFile/LatchDir, Nextflow/Snakemake integration.
Run Python code in the cloud with serverless containers, GPUs, and autoscaling. Use when deploying ML models, running batch processing jobs, scheduling compute-intensive tasks, or serving APIs that require GPU acceleration or dynamic scaling.
How to use it
Take astronomer/managing-astro-local-env from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.