___                     _    __ _ _
  / _ \                   | |  / _(_) |
 / /_\ \ __ _  ___ _ __  | |_| |_ _| | ___
 |  _  |/ _` |/ _ \ '_ \ | __|  _| | |/ _ \
 | | | | (_| |  __/ | | || |_| | | | |  __/
 \_| |_/\__, |\___|_| |_| \__|_| |_|_|\___|
          __/ |
         |___/

Dockerfile for AI agents.

Define your agent once. Run it anywhere. Share it with everyone.

---

The idea is simple

Docker gave us Dockerfile. One file. Any machine. Same result.

AI agents have no equivalent. Every project is a different mess — scattered configs, hardcoded prompts, manual tool setup, README instructions nobody follows.

Agentfile fixes this.

FROM claude-sonnet

SYSTEM "You are an expert software engineer."

TOOL ghcr.io/modelcontextprotocol/server-filesystem:latest  filesystem
TOOL ghcr.io/modelcontextprotocol/server-github:latest      github

MEMORY sqlite://./memory.db

agentfile run

That's it. Your agent is live.

---

Install

# with Go
go install github.com/DeveshB-1/agentfile/cmd/agentfile@latest

# or curl
curl -fsSL https://raw.githubusercontent.com/DeveshB-1/agentfile/main/install.sh | sh

---

The full syntax

# ── Model ──────────────────────────────────────────────────────────────
FROM claude-sonnet          # claude-opus, gpt-4o, llama3, gemini-pro

# ── Personality ────────────────────────────────────────────────────────
SYSTEM "You are a helpful assistant."

SYSTEM """
You are a senior software engineer.
You write clean, idiomatic Go.
You ask clarifying questions when requirements are unclear.
"""

# ── Tools (any MCP container image) ────────────────────────────────────
TOOL ghcr.io/modelcontextprotocol/server-filesystem:latest    filesystem
TOOL ghcr.io/modelcontextprotocol/server-github:latest        github
TOOL ghcr.io/modelcontextprotocol/server-brave-search:latest  brave-search

# ── Memory ─────────────────────────────────────────────────────────────
MEMORY sqlite://./memory.db

# ── Config ─────────────────────────────────────────────────────────────
ENV GITHUB_TOKEN=your_token
ENV BRAVE_API_KEY=your_key

MAX_TURNS 20       # 0 = unlimited

# ── Metadata ───────────────────────────────────────────────────────────
LABEL name="my-agent"
LABEL version="1.0.0"

---

Commands

agentfile init                        # scaffold a new Agentfile
agentfile run                         # run the agent
agentfile run --dry-run               # preview config without applying
agentfile run -f ./agents/Agentfile   # run a specific file
agentfile validate                    # lint your Agentfile
agentfile inspect                     # show parsed config

agentfile push                        # publish to GitHub registry
agentfile pull devesh/coding-agent    # pull anyone's agent
agentfile pull devesh/coding-agent --run   # pull and run in one step
agentfile search "research assistant" # discover community agents

---

The registry

Agentfile uses GitHub as its registry. No signup. No infra. Just Git.

# Publish your agent
export GITHUB_TOKEN=ghp_...
agentfile push

# Anyone can pull it
agentfile pull devesh/coding-agent --run

# Discover agents built by the community
agentfile search "coding"
agentfile search "finance"
agentfile search "research"

Every pushed agent gets tagged topic:agentfile on GitHub — browse the full registry at:

github.com/topics/agentfile

---

Examples

Coding agent — reads files, writes code, pushes to GitHub

FROM claude-sonnet

SYSTEM """
You are an expert software engineer with deep knowledge of system design.
You read existing code before modifying it.
You write tests for every function you create.
"""

TOOL ghcr.io/modelcontextprotocol/server-filesystem:latest  filesystem
TOOL ghcr.io/modelcontextprotocol/server-github:latest      github
TOOL ghcr.io/modelcontextprotocol/server-brave-search:latest brave-search

MEMORY sqlite://./memory.db

ENV GITHUB_TOKEN=your_token

LABEL name="coding-agent"
LABEL version="1.0.0"

agentfile pull devesh/coding-agent --run

Research agent — searches the web, synthesizes, saves findings

FROM claude-sonnet

SYSTEM """
You are a research assistant. Search the web for information,
synthesize findings into clear summaries, and save everything to memory
so you can build on it across sessions.
"""

TOOL ghcr.io/modelcontextprotocol/server-brave-search:latest  brave-search
TOOL ghcr.io/modelcontextprotocol/server-filesystem:latest    filesystem

MEMORY sqlite://./research.db

MAX_TURNS 20

ENV BRAVE_API_KEY=your_key

LABEL name="research-agent"
LABEL version="1.0.0"

Finance agent — tracks markets, analyzes positions

FROM claude-sonnet

SYSTEM """
You are a quantitative financial analyst.
Track market data, analyze positions, and surface key insights.
Always cite your sources and flag uncertainty.
"""

TOOL ghcr.io/deveshb-1/polymarket-mcp:latest              polymarket
TOOL ghcr.io/modelcontextprotocol/server-brave-search:latest brave-search
TOOL ghcr.io/modelcontextprotocol/server-filesystem:latest   filesystem

MEMORY sqlite://./finance.db

ENV POLYMARKET_API_KEY=your_key

LABEL name="finance-agent"
LABEL version="1.0.0"

DevOps agent — monitors infra, runs commands, alerts on anomalies

FROM claude-sonnet

SYSTEM """
You are a senior DevOps engineer. Monitor infrastructure, diagnose issues,
and execute remediation steps. Always explain what you're doing and why.
Ask for confirmation before destructive operations.
"""

TOOL ghcr.io/modelcontextprotocol/server-filesystem:latest  filesystem
TOOL ghcr.io/modelcontextprotocol/server-github:latest      github

MEMORY sqlite://./ops.db

ENV GITHUB_TOKEN=your_token

MAX_TURNS 50

LABEL name="devops-agent"
LABEL version="1.0.0"

---

How it works

agentfile run does three things:

1. Pulls each TOOL container image via Docker or Podman
2. Writes MCP server entries to claude_desktop_config.json
3. Prompts you to restart Claude Desktop

Your agent is live. Change the Agentfile, run again, restart — updated.

agentfile push does three things:

1. Creates a GitHub repo named after your agent
2. Uploads your Agentfile and tags it topic:agentfile
3. Prints a one-liner anyone can use to pull and run it

---

Why this matters

Before Agentfile	With Agentfile
Scattered config files	One file
"It works on my machine"	Reproducible everywhere
Share a wall of setup instructions	agentfile pull you/your-agent
Agents tied to one tool/model	Portable across models and runtimes
No way to version your agent	Git history is your agent history

---

Roadmap

• agentfile run — apply config to Claude Desktop
• agentfile push — publish to GitHub registry
• agentfile pull — pull and run community agents
• agentfile search — discover agents by topic
• agentfile test — run agent against test cases
• Multi-model support (Gemini, GPT-4o, Ollama)
• agentfile.io — cloud hosting, always-on agents
• Web UI for browsing the registry
• Agent composition — FROM devesh/coding-agent

---

Contributing

PRs welcome. The best contribution right now:

Publish your agent. Run agentfile push and add it to the registry. The more agents in github.com/topics/agentfile, the more useful this becomes for everyone.

See CONTRIBUTING.md for code contributions.

---

Built by DeveshB-1 · MIT License

If this saved you time, star it. If it changed how you think about agents, tell someone.