{"id":50711972,"url":"https://github.com/fcrozetta/nephos","last_synced_at":"2026-06-09T16:03:25.972Z","repository":{"id":359677469,"uuid":"1163637737","full_name":"fcrozetta/nephos","owner":"fcrozetta","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-04T23:06:18.000Z","size":807,"stargazers_count":0,"open_issues_count":9,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-04T23:11:17.687Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fcrozetta.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-21T23:15:19.000Z","updated_at":"2026-06-04T21:28:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fcrozetta/nephos","commit_stats":null,"previous_names":["fcrozetta/nephos"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/fcrozetta/nephos","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fcrozetta%2Fnephos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fcrozetta%2Fnephos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fcrozetta%2Fnephos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fcrozetta%2Fnephos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fcrozetta","download_url":"https://codeload.github.com/fcrozetta/nephos/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fcrozetta%2Fnephos/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34114441,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-09T16:03:24.357Z","updated_at":"2026-06-09T16:03:25.961Z","avatar_url":"https://github.com/fcrozetta.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nephos\n\n**Composable self-hosted infrastructure, managed as platform intent.**\n\nNephos is a local-first control plane for running Apps and shared Services on a\nKubernetes cluster you own. It gives self-hosted infrastructure a higher-level\nAPI so installs are not a pile of one-off YAML, Helm values, secrets, and\n`kubectl` commands.\n\nWith Nephos, Apps ask for capabilities. Services provide them. Nephos keeps the\ndesired platform state, reconciles runtime resources, and preserves lifecycle\nsemantics above raw Kubernetes objects.\n\n\u003e [!WARNING]\n\u003e Nephos is early and not production-ready. This repository currently contains\n\u003e the API 0.0.1 backend/control-plane slice.\n\n## Contents\n\n- [QuickStart](#quickstart)\n- [Why Nephos](#why-nephos)\n- [How It Works](#how-it-works)\n- [Advanced: Why Reconciliation Exists](#advanced-why-reconciliation-exists)\n- [What 0.0.1 Gives You](#what-001-gives-you)\n- [Runtime Proof](#runtime-proof)\n- [Maintainer Docs](#maintainer-docs)\n\n## QuickStart\n\n```bash\ncp .env.example .env\n# Edit NEPHOS_API_KUBE_CONTEXT if your Kubernetes context is not docker-desktop.\n\nuv run nephos-api init\nuv run nephos-api serve\n```\n\nThen open the API docs:\n\n```text\nhttp://127.0.0.1:8000/docs\n```\n\nThat starts the Nephos API and its reconciler. It does not install Apps,\ninstall Services, or mutate Kubernetes until you ask Nephos to install\nsomething.\n\nFor local browser routes without editing `/etc/hosts`, keep this in `.env`:\n\n```dotenv\nNEPHOS_API_INTERNAL_DOMAIN=nephos.localhost\n```\n\nYour selected Kubernetes cluster still needs a reachable ingress controller.\n\n## Why Nephos\n\nSelf-hosting gets ugly when every application owns its own database decisions,\nsecret wiring, lifecycle rules, ingress assumptions, and uninstall behavior.\nNephos moves those concerns into one platform control plane.\n\nNephos is built around a simple model:\n\n- Apps are user-facing workloads.\n- Services are shared platform capabilities.\n- Capabilities describe what Apps need, such as `postgres`, `redis`, `s3`, or\n  `search`.\n- Bindings connect Apps to Services without hardcoding the concrete\n  infrastructure into every App.\n- Lifecycle actions preserve intent: stop, start, remove, destroy, and\n  reconcile are platform operations, not raw Kubernetes deletes.\n\n## How It Works\n\n```mermaid\nflowchart TD\n  catalog[\"App and Service catalogs\"]\n  api[\"Nephos API\"]\n  db[(\"SQLite desired state\")]\n  queue[\"Reconciliation requests\"]\n  worker[\"Reconciler\"]\n  providers[\"Python provider layer\\nPulumi + Kubernetes API\"]\n  kube[\"Selected Kubernetes context\"]\n\n  catalog --\u003e api\n  api --\u003e db\n  db --\u003e queue\n  queue --\u003e worker\n  worker --\u003e providers\n  providers --\u003e kube\n  worker --\u003e db\n```\n\n\u003e [!IMPORTANT]\n\u003e SQLite is the source of truth for Nephos desired state. Kubernetes and Pulumi\n\u003e are provider/runtime state reconciled from that intent.\n\nNephos targets the Kubernetes context you select. The goal is not to expose raw\nKubernetes as the user experience; Kubernetes remains the runtime substrate.\n\n## Advanced: Why Reconciliation Exists\n\nWhen you ask Nephos to install or change something, the first job is to record\nwhat you want. The reconciler is the part that turns that saved intent into\nrunning infrastructure.\n\n```mermaid\nflowchart TD\n  request[\"You request a change\"]\n  intent[\"Nephos records desired state\"]\n  reconcile[\"Reconciler works toward that state\"]\n  runtime[\"Kubernetes runtime changes\"]\n  status[\"Nephos reports current status\"]\n\n  request --\u003e intent\n  intent --\u003e reconcile\n  reconcile --\u003e runtime\n  runtime --\u003e status\n  status --\u003e reconcile\n```\n\nThat separation matters because real infrastructure is not instant:\n\n- a cluster can be slow, busy, or temporarily unavailable\n- an App may need a Service, a binding Secret, and an Ingress before it is\n  usable\n- stopping an App should preserve data instead of deleting everything\n- destroying something should be explicit and traceable\n- Nephos should remember what you wanted even if the runtime is not ready yet\n\nFor the user, reconciliation is what makes Nephos a control plane instead of a\ncommand wrapper. You describe the platform state you want; Nephos keeps working\ntoward it, records progress, and exposes status back through the API.\n\n## What 0.0.1 Gives You\n\n- FastAPI backend and `nephos-api` CLI.\n- SQLite desired-state database and migrations.\n- Catalog loading and validation for Apps and Services.\n- API resources for Apps, Services, Bindings, Platform Domains, Catalog, and\n  lifecycle actions.\n- Serialized reconciliation worker.\n- Python provider layer using Pulumi and the Kubernetes API under the hood.\n- PostgreSQL Service provisioning and App binding materialization.\n- Ingress generation with explicit or auto-detected `IngressClass`.\n- Local development route support through `nephos.localhost`.\n\n## Runtime Proof\n\n```bash\nuv run nephos-api dev smoke\n```\n\nThe smoke command proves the end-to-end path: Nephos writes desired state,\nreconciles a reference Service and App, provisions an app-scoped binding,\nchecks route convergence, exercises lifecycle, and cleans up Nephos-owned\nruntime resources.\n\n## Maintainer Docs\n\n\u003cdetails\u003e\n\u003csummary\u003eOperational and implementation references\u003c/summary\u003e\n\n- Manual testing:\n  [docs/testing/api-0-0-1-manual.md](docs/testing/api-0-0-1-manual.md)\n- Current implementation plan:\n  [PLANS.md](PLANS.md)\n- Architecture context:\n  [.agents/context/](.agents/context/)\n- Architecture decision records:\n  [docs/adr/](docs/adr/)\n\n\u003c/details\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffcrozetta%2Fnephos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffcrozetta%2Fnephos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffcrozetta%2Fnephos/lists"}