Get started

Your first project

Create and run your first agent locally
View as Markdown

Go from zero to a running agent in four steps. Have the CLI installed and Docker ready.

1

Create an agent

Create a new agent harness. The name is required; use --model to set the LLM provider:

$ast project create my-agent --model anthropic

After generating the agent harness, the CLI asks what you want the agent to do and prints a prompt to paste into Claude or another coding agent. Pass -y to skip the question and get the prompt immediately.

2

Build your agent logic

The agent harness includes starter source code, astropods.yml, and two files that describe the project to coding agents:

  • AGENTS.md: explains the project structure, the spec format, and the conventions for writing a proper Astropods agent. Any coding agent (Claude Code, Copilot, Cursor, etc.) can read this to understand how to implement and extend your agent correctly.
  • CLAUDE.md: Claude Code-specific instructions for working in this project.

You can write your agent logic manually, or open the project in a coding agent and let it do the heavy lifting:

$cd my-agent
$claude   # Claude Code reads CLAUDE.md and AGENTS.md automatically

Tell it what your agent should do and it will implement the logic, update the spec, and add any required inputs.

3

Configure your agent

Set credentials and API keys required by your agent (e.g. ANTHROPIC_API_KEY):

$ast project configure

The interactive form reads astropods.yml and prompts for each required variable. Values are stored locally and loaded automatically when you start the project. To set a variable non-interactively:

$ast project configure --var ANTHROPIC_API_KEY=sk-...
4

Run your agent locally

Start the local development environment:

$ast project start

Containers start and logs stream automatically in the foreground. Press Ctrl+C to stop everything. To start in the background instead and manage containers manually, use ast project start --background, then ast project logs and ast project stop.

To enable hot reload, add a dev block to astropods.yml:

1dev:
2  command: bun --watch agent/index.ts

Your agent restarts automatically whenever you save a source file.

Next steps

Try a pre-built agent

hello-astro is the simplest possible Astropods agent (no configuration required). Use it to verify your local setup and as a starting point for understanding the project structure.

$git clone https://github.com/astropods/agents.git
$cd agents/hello-astro
$ast project start

Once it’s running locally you can push it to the registry and deploy it as a live agent:

$ast login
$ast blueprint push hello-astro
$ast blueprint deploy hello-astro