Skip to navigation
Build, publish, and deploy

Run your agent locally

Chat with your agent and iterate on it on your machine before you publish
View as Markdown

ast project start runs your agent and its services in Docker containers on your machine, and serves a local chat so you can talk to the agent before you publish a blueprint.

This page assumes you have a project from the Quick start and Docker running. On Windows, see Running agents locally on Windows.

1

Set credentials

Run the interactive form from your project directory:

ast project configure

The command reads astropods.yml for the variables your agent needs and stores your values on your machine. ast project start loads them automatically, so you configure once.

An agent created with --model gateway needs no provider key locally, because the CLI gets a development key for the AI Gateway when you start. An agent created with --model anthropic or --model openai needs that provider’s key.

To skip the form, pass values directly or import a .env file:

ast project configure --var ANTHROPIC_API_KEY=sk-ant-...
ast project configure --vars-file .env
2

Start the agent

ast project start

The command builds your containers, starts them, and tails the agent log in the foreground. Press Ctrl+C to stop everything.

3

Chat with your agent

Open http://localhost:3100. The local chat sends messages through the same messaging service a deployed agent uses, so a reply here exercises the code that runs after you deploy.

4

Change your agent and restart

Edit your agent’s code, press Ctrl+C, and run ast project start again. Each start builds your containers before it runs them. To build without the cache, add --rebuild:

ast project start --rebuild

Run in the background

Start the containers and return to your terminal:

ast project start --background

Then read logs and stop the containers when you finish:

ast project logs            # the agent container
ast project logs <service>  # one sidecar, such as astro-messaging
ast project stop

By default, ast project start shows only the agent’s log. Add --all-logs to tail every service.

Run an ingestion job

If your spec declares an ingestion job, run it against the local environment with ast project trigger <name>. See ast project for the flags.

Next steps

  • Publish a blueprint: push the project to the registry when it works locally
  • ast project: every flag for create, configure, start, logs, stop, and trigger
  • Astropods Spec: declare models, knowledge stores, and other capabilities