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.

Governance

Governance is declared in the agent's frontmatter and enforced by the runtime deterministically, before any tool runs, regardless of what the model decides. Precedence is deny, then require_approval, then auto_approve; without a rule, the default holds: a state-changing tool pauses for your per-call decision. The policy is re-read from the file on every turn, so editing the file mid-run changes the rules immediately.

---
description: Fix log errors in my-api
scope: deployment
deployment: my-api
max_steps: 20
policy:
  auto_approve: [write_deployment_file]   # runs without asking
  require_approval: [get_deployment_logs] # always asks, even read-only
  deny: [control_deployment]              # never advertised to the model
---
Read the recent logs; fix recurring config errors you are sure about.

A run can also start as a dry run: every state change is declined and reported instead of executed, so you see exactly what the agent would have done.

Where This Is Heading

The runtime grows in slices: 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.