skos: the Sovereign Agent OS 🐧

Purpose: the filesystem, packaging, and capability foundation every SKWorld service is deployed through. A Python library + CLI (plus one optional read-only web surface). Status: pre-1.0, active · Maturity-tier: T0 (classical), symmetric-only, no asymmetric key material · License: GPL-3.0-or-later · SOP: SOP.md

Your agents. Your infrastructure. Deploy anything, anywhere, own all of it. One model (ports & adapters), from a laptop to a Kubernetes cluster, personal to enterprise, with zero lock-in.

⚠️ Experimental, pre-1.0, and NOT independently security-audited. skos holds one piece of key material: a local symmetric Fernet key (AES-128-CBC + HMAC-SHA256) that encrypts a single secret blob under $SK_DATA_ROOT/secrets/. There is no asymmetric crypto, no key exchange, and no network crypto here, and the capauth secret backend is a stub that raises. Read SECURITY.md before relying on it.

skos is the filesystem, packaging, and capability foundation of the SKWorld ecosystem. It gives every sovereign service one consistent shape: a data-root abstraction ($SK_DATA_ROOT), an app.yaml descriptor, an OCI packaging adapter, a profile resolver (personal → team → enterprise), a capability catalog (the 4 C's: cloud / comms / compute / core), and a self-building brain (an entity-graph knowledge ontology).

The core idea: every capability (skdata, skmodel, skchat, capauth, …) is a port; every concrete tool (postgres, ollama, matrix, …) is a swappable adapter. You declare what you want; skos resolves how for your profile.

Quickstart

pip install -e .                         # into the ~/.skenv venv
skos init --profile local                # create the data-root tree + show the recommended capability set
skos capabilities                        # list the 4-C capability catalog
skos plan --profile local                # show the resolved install plan (capability → adapter)
skos up --profile local                  # apply: data-root tree + record capabilities
skos path data                           # print an abs path under $SK_DATA_ROOT (apps src data secrets config state cache registry)

Where it lives in SKStack v2

skos is the substrate the whole stack stands on: it defines the filesystem, the descriptor, and the capability/adapter resolution that every other sk* service is deployed through.

flowchart TD
    OP["operator / agent"] -->|"skos up --profile"| SKOS
    subgraph SKOS["**skos** - sovereign agent OS"]
      RES["resolver<br/>(capability → adapter, per profile)"]
      DESC["app.yaml descriptor + renderers<br/>(compose / k8s / nomad)"]
      PATHS["$SK_DATA_ROOT paths + profile"]
      PKG["OCI packaging adapter"]
      BRAIN["brain<br/>(EntityNode ontology, self-build)"]
      SURF["surfaces<br/>(obsidian · claude-code · codex · n8n)"]
    end
    SKOS -->|materializes| CAPS
    subgraph CAPS["the 4-C capability catalog (ports → adapters)"]
      direction LR
      CLOUD["cloud<br/>skfence·skmesh·skdns·skcicd·skinfra·skdweb"]
      COMMS["comms<br/>skcomms·skchat·skvoice·skbus"]
      COMPUTE["compute<br/>skdata·skmodel·skmon·skobject·skfiles·…"]
      CORE["core<br/>capauth·skmemory·sksso·sksec·skvault·skca"]
    end

What skos provides

Piece	What it is
$SK_DATA_ROOT	one data-root abstraction; skos path <subdir> resolves it for the active profile
app.yaml descriptor	the universal service descriptor; skos descriptor validates it
Capability catalog	the 4 C's, every sk* port + its default & alternate adapters (skos capabilities)
Resolver	capability → adapter for a profile (skos resolve <cap> --profile <p>)
Renderers	descriptor → platform manifest (compose / k8s / nomad) (skos render)
Packaging adapter	OCI materialization (skos materialize)
Profiles	personal → team → enterprise; same model, different adapters
Brain	self-building entity-graph knowledge ontology (skos brain init, EntityNode schema)
Surfaces	runtime adapters (obsidian / claude-code / codex / n8n) that expose the brain (skos surface …)
Unified GTD (gtd-ingest)	one GTD, every input an adapter: email/ITIL/cron/calendar/telegram → one capture() sink; daily digests + skos status/skos ingest
Capability packs (skos install <pack>)	pluggable bolt-ons: one signed skworld.module.json (schema v1.2 install facet) activates a whole capability in one command, reversibly. First pack: skbrain (ITIL + CMDB + runbooks, all-or-nothing)

Capability packs (skos install skbrain)

A capability pack is a signed module manifest whose install facet declares an ordered, typed, all-or-nothing install (schema v1.2). The skos planner (skos.packs.planner, PURE) resolves the manifest into a validated, gated plan of typed steps (sql_migration, db_roles, content_repo, seed, fleet_objects, doctor); the provisioner (skos.packs.provisioner) executes it idempotently and fail-safe through an injected side-effect boundary, records per-step state in registry/packs.json, and emits the signed manifest into the shell/Atlas modules dir.

skos install skbrain            # plan (gate on requires) + execute, all-or-nothing
skos install skbrain --dry-run  # show the ordered plan, touch nothing
skos status skbrain             # per-step health (a partial install reads UNHEALTHY)
skos remove skbrain             # reverse activation (fleet objects + manifest); --purge-db for the schema rollback

The installed pack exposes a thin private-knowledge CLI. Database credentials are supplied only through the dedicated projector and reader DSNs; the reader identity cannot write the ops namespace.

This is the beginning of the README. Read the rest at the original. Read the full README ↗