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.

Before you start

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, which reads these files and implements the agent for you:

$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. When startup finishes, you should see the containers come up and the agent’s logs report that it’s ready to accept requests. 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.

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

Next steps