Getting Started

Prerequisites

Node.js 20+ — nodejs.org
Docker — docker.com (Docker Desktop on macOS/Windows, or Docker Engine on Linux). Not required if all agents use the host-user runtime.

1. Create a project

npm i -g @action-llama/action-llama@latest

al new my-agents

cd my-agents

The wizard prompts for your LLM API key (Anthropic recommended) and basic configuration. This creates:

config.toml: project-level settings
.env.toml: local environment binding (gitignored)
package.json: with @action-llama/action-llama as a dependency
CLAUDE.md: a symlink to an AGENTS.md file in the npm package that has everything your agent needs to know
.mcp.json: MCP server config so Claude Code can interact with your agents

2. Create an agent

Add a “dev” agent that will implement Github issues when they are tagged with “ready-for-dev”:

npx al add Action-Llama/agents -a dev

You’ll need to configure the credentials and webhooks since this is the first time you’ve run it. You’ll also want to configure the params to match your Github org. You’ll now see:

agents/dev/
  SKILL.md             # Portable metadata + instructions
  config.toml          # Runtime config (credentials, models, schedule, etc.)

You can also use your agent, such as Claude Code, to create new agents! The CLAUDE.md in the project root has everything it needs to know.

3. Run

npx al start

If any credentials are missing, you’ll be prompted for them. The scheduler starts, discovers your agents, and begins running them on their configured schedules. The terminal shows a live TUI with agent status, or use -w to enable the web dashboard:

npx al start -w

What just happened?

The scheduler scanned for directories with SKILL.md and found your agent
It built a Docker image with your agent’s tools
On the first cron tick, it launched a container, loaded credentials, and started an LLM session
The LLM received your SKILL.md instructions and ran autonomously
When it finished, the container was removed and logs were saved

Key files

File	Purpose
`config.toml`	Project settings: named models, Docker limits, webhook sources
`agents/<name>/SKILL.md`	Portable metadata + agent instructions
`agents/<name>/config.toml`	Agent runtime config: credentials, models, schedule, webhooks, params

Manual test run

Run a single agent once without starting the scheduler:

npx al run dev

What’s next

Using Webhooks — trigger agents from GitHub events
Dynamic Context — use hooks to stage context
Agents (concepts) — understand the runtime lifecycle
CLI Commands — all available commands and flags

First Steps

Guides

Concepts

Integrations

Reference

Prerequisites

1. Create a project

2. Create an agent

3. Run

What just happened?

Key files

Manual test run

What’s next

​Prerequisites

​1. Create a project

​2. Create an agent

​3. Run

​What just happened?

​Key files

​Manual test run

​What’s next

Prerequisites

1. Create a project

2. Create an agent

3. Run

What just happened?

Key files

Manual test run

What’s next