faros

module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 13, 2026 License: Apache-2.0

README

faros

faros connects your distributed Kubernetes clusters and servers through a single control plane — no VPNs, no open firewall ports, no kubeconfig juggling. Agents running on each edge establish outbound reverse tunnels to the hub, so clusters behind NAT, home-lab Raspberry Pis, and bare-metal machines in remote sites all become reachable through one authenticated endpoint.

Features

  • Reverse tunnel connectivity — agents dial out; no inbound firewall rules needed
  • Kubernetes edge support — proxy kubectl to any registered cluster via the hub
  • SSH server mode — manage non-Kubernetes hosts (VMs, bare metal) through the same hub
  • MCP integration — expose all connected clusters as a single Model Context Protocol server for AI agents (Claude, Cursor, etc.)
  • OIDC authentication — plug in any OIDC provider (Dex, Auth0, Okta, …)
  • Static token auth — quick setup for home labs and dev environments
  • Multi-tenant workspaces — per-user/team kcp workspace isolation
  • CLI-first — register edges, get kubeconfigs, and SSH into servers with one command

Architecture

   [ your laptop ]
        │  faros CLI
        ▼
   ┌─────────────┐
   │  faros hub  │  ◄── central control plane (Kubernetes + kcp + OIDC)
   └──────┬──────┘
          │  reverse tunnels (outbound from agents)
    ┌─────┴──────────────────┐
    │                        │
┌───▼────┐             ┌─────▼──────┐
│ agent  │             │   agent    │
│ (k8s)  │             │  (server)  │
│cluster │             │  bare metal│
└────────┘             └────────────┘

The hub is the only component that needs to be publicly reachable. Agents connect outward — NAT and firewalls are not a problem.

Installation

Hub

The hub is the only component that needs a public endpoint. Any device you're comfortable exposing works — a VPS, cloud VM, home server, or anything behind a Cloudflare Tunnel or ingress controller.

→ Installation

CLI

Install the faros CLI on any machine you want to interact with the hub from:

Binary (recommended) — download from the releases page and put the binary in your $PATH.

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@latest

Quickstart

1. Log in

--hub-url defaults to https://console.faros.sh, the hosted hub. Pass your own to use a self-hosted hub.

# Hosted hub
faros login

# Self-hosted hub
faros login --hub-url https://faros.example.com
2. Connect a Kubernetes cluster
# Register the edge on the hub
faros edge create my-cluster --type kubernetes

# Print the agent install command (includes the one-time join token)
faros edge join-command my-cluster

Copy the printed command and run it on the target cluster. Once the agent connects:

faros edge list                                # should show my-cluster as Ready
faros kubeconfig edge my-cluster > kc.yaml    # get a kubeconfig for the edge
kubectl --kubeconfig kc.yaml get nodes
3. Use MCP with AI agents (Claude, Cursor, …)

faros exposes all your connected Kubernetes clusters as a single MCP server, letting AI coding assistants interact with your clusters directly.

# Print the MCP endpoint URL + ready-to-use setup commands
faros mcp url --name default

Example output:

https://hub.example.com/services/mcp/root:faros:user-default/apis/faros.sh/v1alpha1/kubernetesmcps/default/mcp

To add this MCP server to Claude Code:
  claude mcp add --transport http faros "https://hub.example.com/..." -H "Authorization: Bearer <token>"

To add to Claude Desktop (claude_desktop_config.json):
  {
    "mcpServers": {
      "faros": {
        "url": "https://hub.example.com/...",
        "headers": { "Authorization": "Bearer <token>" }
      }
    }
  }

The MCP server aggregates all connected kubernetes-type clusters into one endpoint. AI agents can list pods, describe deployments, apply manifests, and more — across all your clusters at once.

4. Connect a server (SSH mode)
faros edge create my-server --type server
faros edge join-command my-server

Run the printed command on the target host, then:

faros ssh my-server              # interactive shell
faros ssh my-server -- df -h     # single command

CLI Reference

Command Description
faros login Authenticate with the hub (OIDC or static token)
faros edge create <name> Register a new edge
faros edge join-command <name> Print the agent run command with join token
faros edge list List all edges and their connection status
faros edge get <name> Show details for a specific edge
faros edge delete <name> Remove an edge
faros kubeconfig edge <name> Generate a kubeconfig for a Kubernetes-type edge
faros ssh <name> Open an SSH session to a server-mode edge
faros ssh <name> -- <cmd> Run a single command on a server-mode edge
faros agent run Start the agent as a foreground process
faros agent join Install the agent as a persistent service (systemd / Deployment)
faros mcp url --name <name> Print the Kubernetes multi-cluster MCP endpoint URL
faros mcp url --edge <name> Print the per-edge MCP endpoint URL

Documentation

Contributing

See CONTRIBUTING.md for build setup, running tests, and PR guidelines.

License

Apache 2.0 — see LICENSE

Directories

Path Synopsis
apis
admin/v1alpha1
Package v1alpha1 contains the platform-owner-only admin API.
Package v1alpha1 contains the platform-owner-only admin API.
faros/v1alpha1
Package v1alpha1 contains API types for the faros API group.
Package v1alpha1 contains API types for the faros API group.
providers/v1alpha1
Package v1alpha1 contains the platform-owner-only API for managing faros providers (extensions).
Package v1alpha1 contains the platform-owner-only API for managing faros providers (extensions).
tenancy/v1alpha1
Package v1alpha1 contains tenancy API types for user management.
Package v1alpha1 contains tenancy API types for user management.
cmd
faros command
Package main is the entrypoint for the faros CLI.
Package main is the entrypoint for the faros CLI.
faros-hub command
Package main is the entrypoint for the faros-hub server.
Package main is the entrypoint for the faros-hub server.
graphql command
release command
Command release cuts release tags for faros components.
Command release cuts release tags for faros components.
config
kcp
Package kcp embeds kcp configuration files.
Package kcp embeds kcp configuration files.
hack
dex/web
Package web provides embedded web assets for the dex server.
Package web provides embedded web assets for the dex server.
gen-core-apiexport command
gen-core-apiexport merges all individual APIExport YAMLs under config/kcp/ into a single "core.faros.sh" APIExport that covers every API group.
gen-core-apiexport merges all individual APIExport YAMLs under config/kcp/ into a single "core.faros.sh" APIExport that covers every API group.
pkg
agent
Package agent implements the faros agent that connects edges to the hub.
Package agent implements the faros agent that connects edges to the hub.
agent/discovery
Package discovery detects HTTP services running on the edge host next to the agent (e.g.
Package discovery detects HTTP services running on the edge host next to the agent (e.g.
agent/reconciler
Package reconciler reconciles workloads on the agent side: it watches the edge's Placements in the tenant workspace and materializes each as a local Deployment.
Package reconciler reconciles workloads on the agent side: it watches the edge's Placements in the tenant workspace and materializes each as a local Deployment.
agent/status
Package status reports agent status back to the hub.
Package status reports agent status back to the hub.
agent/tunnel
Package tunnel implements reverse-dial tunneling between agent and hub.
Package tunnel implements reverse-dial tunneling between agent and hub.
apiurl
Package apiurl is the single source of truth for all faros service path construction and URL parsing.
Package apiurl is the single source of truth for all faros service path construction and URL parsing.
browsersession
Package browsersession owns the hub's shared browser login session.
Package browsersession owns the hub's shared browser login session.
cli/auth
Package auth handles OIDC authentication for the CLI.
Package auth handles OIDC authentication for the CLI.
cli/cmd
Package cmd implements the faros CLI commands.
Package cmd implements the faros CLI commands.
cli/cmd/dev/cmd
Package cmd provides the faros dev command and its subcommands.
Package cmd provides the faros dev command and its subcommands.
cli/cmd/dev/plugin
Package plugin provides the implementation for faros dev command plugins.
Package plugin provides the implementation for faros dev command plugins.
client
Package client provides dynamic Kubernetes client utilities.
Package client provides dynamic Kubernetes client utilities.
hub
Package hub implements the faros hub server.
Package hub implements the faros hub server.
hub/admin
Package admin implements the platform-admin surface mounted at /api/admin/* and surfaced in the portal's gated /bonkers area.
Package admin implements the platform-admin surface mounted at /api/admin/* and surfaced in the portal's gated /bonkers area.
hub/appauth
Package appauth is the hub's login-time authorization endpoint for published applications.
Package appauth is the hub's login-time authorization endpoint for published applications.
hub/bootstrap
Package bootstrap embeds bootstrap resources for hub initialization.
Package bootstrap embeds bootstrap resources for hub initialization.
hub/controllers/mcpserver
Package mcpserver reconciles MCPServer objects.
Package mcpserver reconciles MCPServer objects.
hub/controllers/organization
Package organization implements the bootstrap controller that gives every User a personal Organization on creation (per docs/organizations.md §Personal Org).
Package organization implements the bootstrap controller that gives every User a personal Organization on creation (per docs/organizations.md §Personal Org).
hub/controllers/softdelete
Package softdelete implements roadmap step 8: the soft-delete reconciler that honours the 30-day grace window from docs/organizations.md decisions O-8 (User delete) and O-13 (Org + Workspace delete).
Package softdelete implements roadmap step 8: the soft-delete reconciler that honours the 30-day grace window from docs/organizations.md decisions O-8 (User delete) and O-13 (Org + Workspace delete).
hub/kcp
Package kcp bootstraps kcp API resources.
Package kcp bootstraps kcp API resources.
hub/mcpaggregate
Package mcpaggregate serves the hub's always-on aggregate MCP endpoint.
Package mcpaggregate serves the hub's always-on aggregate MCP endpoint.
hub/providers
Package providers backs the hub's pluggable-provider extension surface: an in-memory routing table, reverse proxies for /ui/providers/{name}/* and /services/providers/{name}/*, and the controller that keeps the table in sync with ProviderCatalogEntry resources.
Package providers backs the hub's pluggable-provider extension surface: an in-memory routing table, reverse proxies for /ui/providers/{name}/* and /services/providers/{name}/*, and the controller that keeps the table in sync with ProviderCatalogEntry resources.
hub/quota
Package quota implements the quota checks pinned by decisions O-5 (Org quota = soft cap, admin-overridable per User; default 10) and O-6 (Workspace quota = soft cap, admin-overridable per Org; default 50) in docs/organizations.md.
Package quota implements the quota checks pinned by decisions O-5 (Org quota = soft cap, admin-overridable per User; default 10) and O-6 (Workspace quota = soft cap, admin-overridable per Org; default 50) in docs/organizations.md.
hub/restapi
Package restapi implements roadmap step 10: the hub-mediated REST surface for Org / Workspace / Membership / User CRUD per docs/organizations.md decision O-10 ("Org workspaces are hub-mediated only"), plus the undelete actions wired to PR #212's soft-delete reconciler, the self-leave / role PATCH from O-12, and the ?cascade=true shortcut from O-9.
Package restapi implements roadmap step 10: the hub-mediated REST surface for Org / Workspace / Membership / User CRUD per docs/organizations.md decision O-10 ("Org workspaces are hub-mediated only"), plus the undelete actions wired to PR #212's soft-delete reconciler, the self-leave / role PATCH from O-12, and the ?cascade=true shortcut from O-9.
hub/serviceaccounts
Package serviceaccounts implements roadmap step 9 (O-14): bot identity for child Workspaces via native kube `core/v1.ServiceAccount`s marked with faros annotations.
Package serviceaccounts implements roadmap step 9 (O-14): bot identity for child Workspaces via native kube `core/v1.ServiceAccount`s marked with faros annotations.
hub/tenant
Package tenant implements the hub-side tenant middleware described in docs/organizations.md §Switch the active context.
Package tenant implements the hub-side tenant middleware described in docs/organizations.md §Switch the active context.
hub/workloadidentity
Package workloadidentity owns the production provider-action workload capability exchange.
Package workloadidentity owns the production provider-action workload capability exchange.
kcppaths
Package kcppaths is the single source of truth for the faros kcp workspace topology.
Package kcppaths is the single source of truth for the faros kcp workspace topology.
server/auth
Package auth provides server-side OIDC token verification.
Package auth provides server-side OIDC token verification.
server/proxy
Package proxy reverse-proxies authenticated requests to kcp.
Package proxy reverse-proxies authenticated requests to kcp.
util/confighelpers
Package confighelpers provides bootstrap helpers inspired by github.com/kcp-dev/kcp/config/helpers.
Package confighelpers provides bootstrap helpers inspired by github.com/kcp-dev/kcp/config/helpers.
util/conncontext
Package conncontext stores and retrieves net.Conn from context.
Package conncontext stores and retrieves net.Conn from context.
util/identity
Package identity builds the cross-workspace ServiceAccount identity faros authorizes foreign SAs under.
Package identity builds the cross-workspace ServiceAccount identity faros authorizes foreign SAs under.
version
Package version holds build-time version information injected via ldflags.
Package version holds build-time version information injected via ldflags.
test
e2e/cases
Package cases contains shared e2e test case builders that are reused across multiple test suites.
Package cases contains shared e2e test case builders that are reused across multiple test suites.
e2e/framework
Package framework provides shared test infrastructure for faros e2e tests.
Package framework provides shared test infrastructure for faros e2e tests.
e2e/provideractions
Package provideractions contains fixtures shared by the provider-actions E2E suite.
Package provideractions contains fixtures shared by the provider-actions E2E suite.
utils
testfakes
Package testfakes provides shared fake implementations for unit testing controllers that depend on multicluster-runtime manager and cluster interfaces.
Package testfakes provides shared fake implementations for unit testing controllers that depend on multicluster-runtime manager and cluster interfaces.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL