> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.astropods.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.astropods.com/_mcp/server.

# Run your agent locally

`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](/get-started) and [Docker](https://www.docker.com/products/docker-desktop/) running. On Windows, see [Running agents locally on Windows](/install-cli#running-agents-locally-on-windows).

#### Set credentials

Run the interactive form from your project directory:

```bash
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](/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:

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

#### Start the agent

```bash
ast project start
```

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

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

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

```bash
ast project start --rebuild
```

## Run in the background

Start the containers and return to your terminal:

```bash
ast project start --background
```

Then read logs and stop the containers when you finish:

```bash
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`](/cli/project#project-trigger) for the flags.

---

## Next steps

* [Publish a blueprint](/blueprints): push the project to the registry when it works locally
* [`ast project`](/cli/project): every flag for create, configure, start, logs, stop, and trigger
* [Astropods Spec](/astropods-package-spec): declare models, knowledge stores, and other capabilities