Agents

An agent is a plain markdown file that describes work the server can do: optional frontmatter for its scope, a body of instructions. The runtime is the layer underneath that executes it, the same one behind the assistant and the MCP server: the tool loop, permission gates, protected mode, secret redaction, and the governance that decides what runs freely, what needs your sign-off, and what never runs.

Creating an Agent

Three equivalent paths, all producing the same file:

• Ask the assistant. Describe what you want in chat; the assistant drafts the file and writes it through a governed tool.
• The Agents view. Write or edit the file in the panel, with validation on save.
• The filesystem. Any editor, git, CI, or another agent. It is a plain file.

---
description: Summarize recent errors in the logs
scope: deployment
deployment: my-api
---
Read the recent logs and the compose file. Summarize any
errors you find, and propose a fix for each.

Runs

Running an agent executes its instructions as an AI session through the runtime, so every session guarantee carries over:

• Every action runs as an authenticated actor with its own permissions.
• Governance gates state changes; protected deployments refuse them outright.
• Secrets are redacted before anything leaves your server.
• Each run records its agent, so an agent's run history is its sessions.

Why Markdown

FlatRun's premise is that everything is a flat file you can read, edit, and version. An agent follows the same rule. Instead of orchestration hidden behind a UI or a proprietary format, an agent is a document:

• Readable. Anyone on the team can open it in any editor and understand what the agent does.
• Versioned. It lives in git alongside your deployments, with a full history and review.
• Portable. No black box. The file is the whole definition.

Where This Is Heading

The runtime grows in slices: declarative governance policy in frontmatter (what auto-runs, what always asks, what is denied), durable runs that park themselves and wake on schedules or webhooks, and external tools attached over MCP so agents can reach systems like source forges and coding tools, all under the same governance. Because agents can also write agent files, a system can refine itself, with every change surfaced rather than silent.