faros is an open-source control plane for platform teams.
Providers publish Kubernetes-style APIs, versioned actions and MCP tools into isolated tenant workspaces. Users, teams and organizations reach them through one portal, one CLI, one API and one MCP endpoint, and every call is authorized as the caller by the same RBAC. Edges extend the control plane to clusters and servers behind NAT through outbound tunnels, so the same workspace that holds an application also reaches the cluster it runs on.
Status: alpha. faros is at v0.1.x, every API is
v1alpha1, and it is developed by a small team. There is no hosted service; you run the hub yourself. Expect breaking changes between minor versions until the APIs stabilize.
- Tenancy. Organizations, teams and users each get an isolated workspace with its own API surface. Membership and roles are first-party APIs. Authenticate with any OIDC provider or, for a single user, a static token.
- Providers. Helm-installed extensions that bring an APIExport, controllers, a backend, a portal micro-frontend, MCP tools and actions. Tenants enable a provider in a workspace and get its APIs bound there. Organizations can also register providers they run themselves, reached over an edge (BYO providers).
- Provider actions. Versioned verbs on resources, granted through the workspace's RBAC, callable by people and by agents (design).
- One MCP endpoint per workspace. Tools from every enabled provider and every connected edge, aggregated into one Model Context Protocol server. Each tool call runs as the calling user (architecture).
- Edges. Kubernetes clusters and Linux servers join through an agent that dials out. The hub proxies
kubectl, SSH and selected in-cluster services to them. - A portal. One web UI that hosts each provider's micro-frontend under the tenant's identity.
| Provider | What it does |
|---|---|
| edges | Connectivity: KubernetesCluster and LinuxServer edges, the agent tunnel, Service connectors, per-edge MCP |
| infrastructure | Brokers kro application templates into tenant workspaces and runs them on a runtime cluster |
| app-studio | Persistent AI project workspaces with a chat assistant, sandboxed development instances and publishing, on the tenant's own model credentials |
| agents | Long-running personal agents with scheduled runs, tool use, approvals, budgets and memory, reachable from Slack, Telegram, Discord and email |
| code | Source repositories, deploy keys and collaborators as workspace resources, on GitHub today |
| databricks | Databricks connections, warehouses and tables as workspace resources, with a query_table action |
| kuery | Fleet-wide object search and relationship traversal across a workspace's connected clusters |
| quickstart | A minimal reference provider that exercises the whole plugin surface |
Provider directories are mirrored read-only to faroshq/provider-* repositories. Open changes here.
people · CLI · portal · AI agents (MCP)
│
┌────────▼────────┐
│ faros hub │ workspaces, OIDC, RBAC,
│ │ provider registry, proxies
└──┬─────┬─────┬──┘
provider APIs │ │ │ outbound tunnels
┌────────────────────┘ │ └────────────────────┐
┌─────▼──────┐ ┌────────▼───────┐ ┌──────▼──────┐
│ platform │ │ org-owned │ │ edges │
│ providers │ │ providers │ │ clusters & │
│ (in-cluster│ │ (your cluster, │ │ servers │
│ with hub) │ │ over an edge) │ │ behind NAT │
└────────────┘ └────────────────┘ └─────────────┘
The hub is the only component that needs to be reachable. Providers register with the hub and serve their APIs inside their own workspace; agents on edges connect outward. Traffic between the hub and everything else is HTTP/1.1 and WebSockets, so any reverse proxy, ingress or tunnel in front of the hub works.
helm install faros-hub oci://ghcr.io/faroshq/charts/faros-hub \
--namespace faros --create-namespace \
--set hub.hubExternalURL=https://faros.example.comThat is a complete single hub; its control-plane store runs inside the same release. For TLS, OIDC, ingress and the provider hardening flags, see Helm deployment. Larger installs can run the control-plane store as separate shards: single hub, multi-shard.
To try faros on a laptop, the CLI can create a local hub in a kind cluster:
faros dev initDownload a binary from the releases page, or:
# krew
kubectl krew index add faros https://github.com/faroshq/krew-index.git
kubectl krew install faros/faros
# from source
go install github.com/faroshq/faros/cmd/faros@latestfaros login --hub-url https://faros.example.com # OIDC in the browser
faros login --hub-url https://faros.example.com --token <static-token>
faros use # choose organization and workspace--hub-url can also come from FAROS_HUB_URL.
faros edge create my-cluster --type kubernetes
faros edge join-command my-cluster # prints the agent install command with a one-time tokenRun the printed command on the target cluster. Then:
faros edge list
faros kubeconfig edge my-cluster > kc.yaml
kubectl --kubeconfig kc.yaml get nodesfaros edge create my-server --type server
faros edge join-command my-server
faros ssh my-server -- uptimefaros mcp url --name defaultThis prints the workspace's MCP endpoint and ready-to-paste configuration for Claude Code and Claude Desktop. The endpoint carries the tools of every enabled provider and every connected edge, and each call is authorized as you.
The hub authenticates users with OIDC or a static token, and providers with their own workspace service-account token. Org-owned providers never see a user's bearer: they receive a short-lived, workspace-bound delegated token. Agents refuse to proxy to link-local and metadata addresses and can be locked to an allow-list. Webhooks into the agents provider are signature-checked. Details are in Security.
Some hardened behaviours ship off by default for one release so existing installs can roll forward; the Helm doc's section "Turning on the hardened defaults early" lists the values that turn them on.
To report a vulnerability, open a private security advisory on this repository rather than a public issue.
| Command | What it does |
|---|---|
faros login |
Authenticate with a hub via OIDC or static token |
faros use |
Switch the active organization and workspace |
faros edge create|list|get|delete <name> |
Manage edges |
faros edge join-command <name> |
Print the agent join command for an edge |
faros edge upgrade <name> |
Print upgrade instructions for an edge agent |
faros kubeconfig edge <name> |
Generate a kubeconfig that reaches an edge through the hub |
faros ssh <name> [-- cmd] |
Open a shell or run a command on a server edge |
faros mcp url --name <name> / --edge <name> |
Print the workspace or per-edge MCP endpoint |
faros get, faros apply |
Read and apply workspace resources |
faros agent join|run|install|uninstall|upgrade |
Run or install the agent on a cluster or host |
faros dev init|update|delete |
Manage a local kind-based environment |
faros get-token |
OIDC token for a kubectl exec credential plugin |
| Path | Contents |
|---|---|
cmd/ |
faros CLI (which also runs the agent through faros agent), faros-hub, the GraphQL gateway, and the release helper |
pkg/hub |
Hub: control-plane bootstrap, tenancy, provider registry, proxies, MCP aggregation |
pkg/agent |
Edge agent and tunnel |
providers/ |
The providers listed above, each its own Go module |
deploy/charts |
Helm charts for the hub and the agent |
docs/ |
Published docs and design documents |
Published: Getting started · Helm deployment · Security · Ingress · MCP architecture · Developer guide
Design documents in this repository: providers, organizations and the workspace tree, provider scoping, provider actions, BYO providers, MCP architecture.
Workspaces are served by kcp, which gives every tenant a Kubernetes-style API server without a cluster per tenant; providers publish their APIs into it and tenants bind them. You meet this as an operator when you size and back up the hub, and as a provider author when you write one. Users see the portal, the CLI, the API and MCP.
See CONTRIBUTING.md for building, running the local stack, tests and the pull-request workflow.
Apache 2.0. See LICENSE.