faros

module
v0.1.30 Latest Latest
Warning

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

Go to latest
Published: Sep 12, 2026 License: Apache-2.0

README

faros

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.

What faros gives you

  • 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.

Providers in this repository

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.

How it fits together

                 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.

Install

Hub
helm install faros-hub oci://ghcr.io/faroshq/charts/faros-hub \
  --namespace faros --create-namespace \
  --set hub.hubExternalURL=https://faros.example.com

That 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 init
CLI

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

Quickstart

1. Log in and pick a workspace
faros 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.

2. Connect a cluster
faros edge create my-cluster --type kubernetes
faros edge join-command my-cluster        # prints the agent install command with a one-time token

Run the printed command on the target cluster. Then:

faros edge list
faros kubeconfig edge my-cluster > kc.yaml
kubectl --kubeconfig kc.yaml get nodes
3. Connect a server
faros edge create my-server --type server
faros edge join-command my-server
faros ssh my-server -- uptime
4. Give an AI agent your workspace
faros mcp url --mcpserver-name default

This prints the workspace's MCP endpoint and ready-to-paste configuration, with its long-lived token, for Claude Code, Claude Desktop and Codex. The endpoint carries the tools of every enabled provider and every connected edge, and each call is authorized as you.

Security

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.

CLI reference

The full, generated reference is in docs/cli (one page per command, regenerated with make docs-cli). faros --help groups the commands the same way; faros completion --help sets up shell completion.

Command What it does
faros login --hub-url <hub> [--token t] [-i] Log in (browser OIDC with silent refresh, or a static token); writes the faros kubeconfig context
faros logout Forget the cached tokens and the faros contexts on this machine
faros use [--org O --workspace W] Switch the active organization and workspace (interactive picker without flags)
faros whoami [-o json] Hub, identity, token state, org/workspace with your roles, and what kubectl points at
faros token [--refresh] Print a current bearer for curl; --refresh forces the OIDC refresh grant
faros edge create|list|get|delete <name> Manage edges; list/get take -o wide|json|yaml|name
faros edge join-command|upgrade <name> Print the agent join command or upgrade instructions
faros edge kubeconfig <name> [-o file|--merge] Kubeconfig for a cluster edge through the hub, standalone or merged as context faros-<name>
faros connect [<edge>] / faros disconnect Point kubectl at a cluster edge and back at the hub workspace
faros ssh <name> [-- cmd] Open a shell or run a command on a server edge
faros org list|create|members … Organizations you belong to; members list|add|remove|set-role manage access
faros workspace list|create|members … Workspaces of an organization and their members
faros mcp url --mcpserver-name <name> / --edge <name> Print the workspace or per-edge MCP endpoint
faros env [--json] [--no-mcp] Print HUB, CLUSTER, ORG, WS, TOKEN, AS, MCP_URL, MCP_TOKEN as shell exports
faros app list|create|status|sync|promote|publish Manage App Studio projects
faros commit <repositoryRef> [--branch main] [--dry-run] Record local git commits through faros (code__commit_files)
faros sandbox sync|exec|logs|restart|status <instance> [component] Drive a development-mode instance through the data plane
faros agent join|run|install|uninstall|upgrade, faros install Run or install the agent on a cluster or host
faros dev init|update|delete Manage a local kind-based environment

Hidden but still accepted: faros list/ls (edge list), faros kubeconfig edge, faros get, faros apply, faros get-token (the kubectl exec plugin) and faros kcp-workspace (raw kcp workspace navigation).

Building an app from a terminal or an AI agent

These commands call the hub REST and MCP APIs as you, resolving the org and workspace UUIDs from the kubeconfig's faros context. Every one takes --org / --workspace (display name or UUID) to target another workspace, and the app and sandbox commands take -o json for raw output.

eval "$(faros env)"                          # exports for curl and scripts
faros app create shop --template application --display-name Shop --wait
faros app status shop                        # repository ref, commits, dev URL, promotion, publishing
gh repo clone <owner>/<repository ref> shop && cd shop
faros sandbox sync shop-dev api ./api        # authoritative sync of api/ into component "api"
faros sandbox exec shop-dev api -- node -e 'console.log(1)'   # exits with the command's exit code
faros sandbox logs shop-dev api -f
git add -A && git commit -m "Add cart"       # commit locally, never push
faros commit <repository ref>                # faros records the commit; your branch is reset onto it
faros app promote shop --hostname-prefix shop   # the prefix is locked after the first promote
faros app publish shop --mode public         # or restricted, or private

faros commit refuses to run when the working tree is dirty or origin/<branch> has moved past your base. faros commit and faros sandbox sync send binary files base64-encoded (at most 25 MiB each, 48 MiB per commit or sync) when the hub's code provider or the component's dev agent supports it. Otherwise commit refuses a change that includes binaries and sync skips them with a warning. exec needs a prior sync.

Repository layout

Path Contents
cmd/ faros CLI (which also runs the agent through faros agent), faros-hub, 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

Documentation

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.

Under the hood

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.

Contributing

See CONTRIBUTING.md for building, running the local stack, tests and the pull-request workflow.

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.
faros-runner command
Command faros-runner serves the loopback-only generic runner protocol.
Command faros-runner serves the loopback-only generic runner protocol.
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.
edges-macos command
Command macos-stub is a localhost-only health endpoint used to validate the Edges Service transport on a MacOSServer.
Command macos-stub is a localhost-only health endpoint used to validate the Edges Service transport on a MacOSServer.
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.
govulncheck command
govulncheck-filter turns `govulncheck -format json` output into a blocking CI gate with an auditable allowlist.
govulncheck-filter turns `govulncheck -format json` output into a blocking CI gate with an auditable allowlist.
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/membershipindex
Package membershipindex implements the UMI invariant reconciler: a controller that watches UserMembershipIndex CRs in root:faros:users and repairs rows that strand a user.
Package membershipindex implements the UMI invariant reconciler: a controller that watches UserMembershipIndex CRs in root:faros:users and repairs rows that strand a user.
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/hubaccess
Package hubaccess implements the hub-access half of the provider contract: the hub REST capabilities a provider may exercise with the delegated user token the hub hands it in place of the caller's bearer.
Package hubaccess implements the hub-access half of the provider contract: the hub REST capabilities a provider may exercise with the delegated user token the hub hands it in place of the caller's bearer.
hub/kcp
Package kcp bootstraps kcp API resources.
Package kcp bootstraps kcp API resources.
hub/leaderelection
Package leaderelection gates the hub's singleton controllers so a hub scaled to multiple replicas still reconciles each object exactly once.
Package leaderelection gates the hub's singleton controllers so a hub scaled to multiple replicas still reconciles each object exactly once.
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/sharedstore
Package sharedstore is the hub's cross-replica key/value store for short-lived login state: browser sessions and published-app authorization codes.
Package sharedstore is the hub's cross-replica key/value store for short-lived login state: browser sessions and published-app authorization codes.
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.
runner
Package runner provides a durable, authenticated local execution service.
Package runner provides a durable, authenticated local execution service.
runner/harness
Package harness defines the public execution seam for runner adapters.
Package harness defines the public execution seam for runner adapters.
runner/harness/codex
Package codex adapts the Codex app-server protocol to the runner harness.
Package codex adapts the Codex app-server protocol to the runner harness.
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