Quick start

This guide takes you from an empty directory to a running agent in about five minutes: you write one file, validate it, and run it. Everything runs through Docker, so there is nothing else to install.

0. Prerequisites

• Docker - agents run from the published base image, ghcr.io/loopedautomation/agent
• An API key for an OpenAI-compatible or Anthropic endpoint - or a local model via Ollama, no key required

1. Write the agent file

An agent is defined entirely by a single file. Create a project directory, then add the definition as agent.yaml:

mkdir time-bot && cd time-bot

# agent.yaml
handle: time-bot
description: Answers questions, and knows what time it is.

model:
  provider: openai-compatible
  id: gpt-5.4-mini

purpose: |
  You are a concise assistant. When asked about the current date or time,
  use the current_time tool rather than guessing.

# agent.yaml
handle: time-bot
description: Answers questions, and knows what time it is.

model:
  provider: anthropic
  id: claude-haiku-4-5

purpose: |
  You are a concise assistant. When asked about the current date or time,
  use the current_time tool rather than guessing.

• The handle is the identifier you use to refer to the agent. The agent chooses its own display name on first boot and announces it in a startup banner.
• Unknown keys are validation errors, so a misspelled key such as permisions: fails immediately instead of being silently ignored.
• To use a local model instead, use the openai-compatible provider and add base_url: http://host.docker.internal:11434/v1 under model: - no API key is needed. (localhost would resolve to the container itself; on Linux, also add --add-host=host.docker.internal:host-gateway to the commands below.)

Every block is explained in Agent config.

2. Validate it

Validation is the same for both providers:

docker run --rm -v ./agent.yaml:/agent/agent.yaml:ro \
  ghcr.io/loopedautomation/agent:latest validate /agent/agent.yaml

Prints the parsed identity, compiled sandbox flags and every env var the config references, with a warning for any that aren't set.

3. Run it

export OPENAI_API_KEY=sk-...
docker run --rm -it \
  -v ./agent.yaml:/agent/agent.yaml:ro \
  -e OPENAI_API_KEY \
  -v time-bot-data:/data \
  ghcr.io/loopedautomation/agent:latest

export ANTHROPIC_API_KEY=sk-ant-...
docker run --rm -it \
  -v ./agent.yaml:/agent/agent.yaml:ro \
  -e ANTHROPIC_API_KEY \
  -v time-bot-data:/data \
  ghcr.io/loopedautomation/agent:latest

Meridian (time-bot) is listening (model: gpt-5.4-mini; ctrl-d to exit)
you> what time is it?

Meridian> It's 21:14 UTC on July 3, 2026.

[ok · 2 steps · 743in/41out tokens · $0.000136]

Your first agent is now running locally. The image's default command runs the mounted config, and the /data volume holds the agent's memory and identity - persist it and the agent keeps the name it chose. Every run reports its status, step count and token usage.

What's next

Without triggers:, running the agent starts an interactive REPL, which is the fastest way to iterate on a purpose. From here you can:

• Give it triggers and the same image runs a long-lived service: Discord · Webhook · Cron
• Teach it skills and wire up tools: Skills · Tools
• Grant it capability safely: Permissions
• Ship it for real, from the base image to fleets and PaaS: Docker run · Docker compose
• Generate a complete project instead of writing the files by hand - af init scaffolds the agent, secrets and deployment shape: CLI
• Start from a complete, runnable agent: the gh-issues-cli example uses the same file shape, adds triggers, skills and permissions, and deploys with docker compose up