Getting Started

Introduction

FlatRun is a self-hosted hosting OS with a full platform API and an agent engine, all defined as flat files with no lock-in.

FlatRun is an open-source, self-operating server: a hosting OS with a full platform API and an agent engine, running on infrastructure you control. Deploy apps, databases, and SSL, drive everything through the API, and define agents that carry out work under the governance you set. It runs on standard Docker Compose, and everything is a flat file you can read, version, and walk away with.

Our Philosophy

We believe infrastructure should not be magical or locked-in. Too many server management tools hide your configuration in databases, proprietary formats, or obscure volume directories. This makes migrations painful and gives vendors leverage to increase prices, because leaving is hard.

Tools like Portainer store compose files in numbered folders inside volumes, making it difficult to understand or recover your setup. Control panels like Plesk have steadily increased prices over the years, knowing that migration is a nightmare for their users.

FlatRun takes a different approach:

  • Flat Files Everything lives on the filesystem in plain, readable directories
  • Recognized Standards Standard docker-compose.yml files you can use anywhere
  • No Lock-in Walk away anytime with docker compose up
  • Full Transparency No hidden databases, no magic, no surprises

What is FlatRun?

At its core is the FlatRun Agent: a single Go service that runs your deployments, handles SSL and Nginx, and exposes everything through a full REST API. On top of that API sits an agent engine: a shared tool loop with permission gates and governance that powers the assistant, the MCP server, and agents you define as flat files.

You reach it however you like, and every path goes through the same governed API:

  • The UI: a modern Vue.js dashboard for people.
  • The API and CLI: for scripts, CI/CD, and automation.
  • The MCP server: the same tool set, for external AI clients.
  • Agents: plain markdown files the engine runs on your behalf.

Key Features

  • AI Assistant A built-in assistant with tool calling that diagnoses deployments, suggests fixes, and carries out actions under the governance you set. Bring your own model.
  • Agents Define agents as plain markdown files; the engine runs them through governed tools, so what runs freely, what needs sign-off, and what never runs is yours to set.
  • MCP Server Expose the assistant's tool set to external MCP clients, with the same permission checks. One tool set, many front doors.
  • Platform API Every capability is a REST endpoint, so the whole server is scriptable and automatable.
  • Templates Deploy popular applications like WordPress, Ghost, Laravel with pre-configured templates.
  • Standard Docker Compose Uses standard docker-compose files you already know.
  • Automatic SSL Let's Encrypt integration for automatic certificate provisioning and renewal.
  • Reverse Proxy Built-in Nginx integration for domain routing.
  • Database Management Manage MySQL, MariaDB, and PostgreSQL databases directly from the UI.
  • Clustering Connect multiple FlatRun nodes together for distributed deployments and high availability.
  • Backup & Restore Automated backup scheduling with one-click restore for your deployments.
  • Security Threat detection, IP blocking, rate limiting, and security event monitoring.
  • Scheduled Tasks Cron-based task scheduling for recurring operations on your deployments.
  • Audit Logging Complete audit trail of all actions across the platform.
  • Traffic Analytics Monitor request volumes, response codes, and traffic patterns per deployment.
  • Multi-User with RBAC Role-based access control with admin and user roles.
  • Real-Time Monitoring View container logs, resource usage, and health status.
  • CLI & CI/CD The flatrun CLI and official GitHub Action deploy from any compatible runner.
  • Self-Hosted Run on your own server with complete control.

How it Works

FlatRun uses a simple filesystem-based approach. Each container stack is a directory with a standard docker-compose.yml file. The agent watches this directory and manages the container lifecycle. 

/var/flatrun/
├── nginx/                    # Reverse proxy (managed by agent)
│   ├── conf.d/              # Virtual host configs
│   └── certs/               # SSL certificates
├── my-blog/                  # Your container stack
│   ├── docker-compose.yml   # Standard compose file
│   └── service.yml          # Optional: FlatRun metadata
└── my-api/                   # Another stack
    └── docker-compose.yml

When you create a container through the UI or API, the agent:

  1. Creates the directory with your docker-compose.yml
  2. Configures Nginx if you specify a domain
  3. Obtains SSL certificates via Let's Encrypt
  4. Runs docker compose up to start your containers

If you ever want to leave FlatRun, your containers keep running. Just use standard Docker commands; there's nothing proprietary to untangle.

Who is FlatRun For?

  • Developers Self-host your side projects and applications.
  • Small Teams Simple container management without Kubernetes complexity.
  • Hobbyists Run home servers or VPS instances with ease.
  • Agencies Manage multiple client projects on dedicated servers.

Getting Help

If you run into issues or have questions:

Next Steps

Quick Start Get FlatRun running in minutes Core Concepts Understand how FlatRun works
Star us on GitHub