faros Documentation

faros is an operating system for platforms. Not a portal that describes your infrastructure — a control plane that runs it, with the same primitives available to humans, controllers, and AI agents.

It gives you four things, and everything else is written against them:

New here? Read Concepts for how those four fit together, or jump straight to the Quickstart .

Agents get a platform. Not root.

An AI agent operating real infrastructure usually gets one of two things: no access at all, or a god-mode kubeconfig. faros gives it the third option that operating systems settled on decades ago — userspace.

• An agent is issued credentials for one workspace. It cannot address anything outside it; the request never reaches a place where the answer exists.
• Every action is a declarative API object you can list, diff, audit, and revert — not an imperative side door.
• MCP tools are derived from the same RBAC that governs the API, so “what can this agent do?” has exactly one answer, changed in one place.

No inbound rules. No VPNs. No port forwarding.

The hub is the only thing with a public endpoint. Everything else stays behind its firewall — and still becomes reachable.

   Your laptop                    Hub                           Edge
   ──────────                    ────                          ─────

   kubectl/faros  ──────────►  ┌─────────────┐  ◄─── dial out ──  agent
                               │  faros hub  │  (outbound only)  (k8s cluster)
                               │  (public)   │                   bare metal
                               └─────────────┘                   VM / Raspberry Pi
                                                                 behind NAT/firewall

How it works: Agents dial out to the hub. The hub keeps a reverse tunnel open. Every time you run kubectl or kubectl faros ssh, your request goes to the hub, which forwards it through that existing tunnel. Nothing needs to reach into your network.

Works where other tools fail

Two ways to run it

Both produce the same CLI experience.

• Hosted hub at console.faros.sh — sign in, register an edge, get a kubeconfig. Fastest way to try it.
• Self-host your own hub — one Helm chart on any Kubernetes cluster, behind a VPS / Cloudflare Tunnel / nginx. No license keys, no telemetry, no usage limits.

What’s in this documentation

Pick whichever path fits where you are.

• Concepts — the OS model: workspaces, providers, MCP, and edges, and how a request flows through them.
• Get started — install the CLI, log in, connect your first edge.
• CLI reference — every command: auth, orgs and workspaces, edges, agents, SSH, MCP.
• Deploy your own hub — Helm, ingress options, Cloudflare Tunnel.
• Security & tenancy — static tokens, OIDC, organizations, workspaces, service accounts.
• Building providers — write your own driver: APIs, controllers, UI, and MCP tools; plus the catalog of providers that ship in the box.