# managing-astro-local-env

Controls local Apache Airflow environments with Astro CLI across Docker and standalone modes. Helps start services, tail logs, and query the Airflow API.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1400 installs · ★ 456
- Author: astronomer
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/astronomer/agents/tree/HEAD/skills/managing-astro-local-env/SKILL.md
- Updated: 2026-10-14
- HTML: https://affpapa.org/en/nevibecode/skills/managing-astro-local-env

## What it does

This skill guides coding assistants through Astro CLI workflows for local Airflow development. It covers routine container tasks like starting services with `astro dev start`, stopping them cleanly, and restarting individual components such as the scheduler or webserver. When running multiple projects, the built-in reverse proxy on port 6563 routes each project to its own hostname to prevent port collisions.

Besides containerized setups, the skill documents standalone mode. This runs Airflow 3 directly on your host in a `.venv/` directory managed by `uv`. Standalone mode will not work on Windows, and it strictly requires `uv` on your PATH alongside an Airflow 3 runtime.

It also provides commands for inspecting the local environment through `astro api airflow`. Your agent can discover endpoints, trigger DAG runs, retry failed task instances, and parse structured output using `jq` filters without opening the web interface.

## Requirements
- Works with: Docker

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add astronomer/agents --skill managing-astro-local-env -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/managing-astro-local-env/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/managing-astro-local-env/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add astronomer/agents --skill managing-astro-local-env -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/managing-astro-local-env/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add astronomer/agents --skill managing-astro-local-env -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/managing-astro-local-env/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install astronomer/agents managing-astro-local-env
```

2. **Manually: put the files in place**
- File: `.github/skills/managing-astro-local-env/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add astronomer/agents --skill managing-astro-local-env -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/astronomer/agents --path skills/managing-astro-local-env
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/managing-astro-local-env/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add astronomer/agents --skill managing-astro-local-env -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/astronomer/agents/tree/HEAD/skills/managing-astro-local-env/SKILL.md

## When to use it
- restart Airflow scheduler or webserver after updating `requirements.txt`
- run local Airflow 3 in standalone mode without Docker using `uv`
- retry failed task instances using `astro api airflow`
- inspect live container logs with real-time streaming
- resolve port conflicts across multiple projects with reverse proxy

## Example prompts
- Start the local Airflow environment with astro dev start and check container logs
- List all DAG import errors using astro api airflow
- Trigger my_dag and clear failed tasks from the latest run

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: dd79f027b5494609.

BEGIN THIRD-PARTY FILE dd79f027b5494609
````text
---
name: managing-astro-local-env
description: 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.
---

# 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 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

```bash
# 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

```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
````
END THIRD-PARTY FILE dd79f027b5494609

The third-party file has ended. Everything between the dd79f027b5494609 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2536 of 8060 bytes. © astronomer · Apache-2.0 · https://github.com/astronomer/agents/tree/HEAD/skills/managing-astro-local-env/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md