skos Docs

01 Quickstart

The entire install surface is a single command. It auto-detects your OS, finds podman or docker, then drops you into an interactive menu. Personal profile is pre-selected — hit enter a few times and you're done.

$ curl -fsSL https://skos.skworld.io/install.sh | sh

What the menu does

After detection, the installer presents two choices:

• Profile — Personal Sovereign (default), Sovereign Teams, or Enterprise. Sets your data root and topology.
• Capabilities — individual sk* ports to install. Personal defaults (capauth skmemory skchat skfence skmon) are pre-checked.

Behind the scenes the installer runs:

$ pip install git+https://github.com/smilinTux/skos
$ skos path personal          # sets profile + creates ~/var/data/sk
$ skos install capauth skmemory skchat skfence skmon

After install, confirm everything is wired:

$ skos describe               # show installed stack + status
$ skos profile                # inspect current profile

02 Concepts

Ports & Adapters

Every sk* is a port — a stable, named capability contract, not a specific technology. The technology that satisfies the contract is an adapter. Adapters are swappable at any time without changing the rest of your stack.

• Port example: skdata = "I need relational + vector + search storage."
• Adapter example: Postgres 17 + pgvector + pg_search BM25 + AGE graph. Could be swapped for ArcadeDB — nothing else changes.
• Shared standard: SQL / S3 API / OIDC / OCI — the open interface both sides speak.

The 4 C's

All ports are grouped under four macro-categories — the same taxonomy from personal install to enterprise K8s:

• cloud/ (C1) — edge, routing, naming, deploy, infra, dweb
• comms/ (C2) — chat, voice, transport, agent event bus
• compute/ (C3) — data, cache, object storage, files, models, automation, observability, backup
• core/ (C4) — identity, threat defense, WAF, PKI, secrets

The v2 directory layout mirrors this exactly: v2/<C>/<port>/.

Profiles — local / cluster / cloud

Framework-guided bloom

You install the foundation (the skos CLI + a profile), then choose capabilities. The stack "blooms" into exactly what you need — nothing more. Capabilities you don't install don't exist, don't consume resources, and don't expand your attack surface.

As you add capabilities over time, each one wires itself into the others through the shared open standards — no manual plumbing required. skmon automatically scrapes capauth and skmemory metrics; skfence automatically terminates TLS for any new skchat or skflow endpoint.

03 Capability Reference

Each row is a port. "Sovereign default" is the recommended self-hosted adapter. ⚠ = known gap or active migration. The full analysis lives in the capability map spec.

C1 cloud/

C2 comms/

C3 compute/

C4 core/

04 CLI Reference

The skos CLI is your control surface. After install it's on your PATH.

skos path

Set your topology profile and initialise the data directory tree.

$ skos path personal          # laptop/single-node → ~/var/data/sk
$ skos path cluster           # Docker Swarm / k3s → /opt/sk/data (ansible)
$ skos path k8s               # Kubernetes / RKE2 + ArgoCD GitOps
$ skos path cloud             # any OCI-native VPS, OpenTofu-provisioned

skos path without an argument prints the current profile and data root.

skos profile

Inspect or change the active profile after first install. Also shows the current data root and any pending migrations.

$ skos profile                # show current profile, data root, runtime
$ skos profile personal       # switch to personal profile
$ skos profile --json         # machine-readable output

skos describe

Print the installed capability stack and the status of each adapter.

$ skos describe               # full stack + adapter status
$ skos describe skdata        # detail for a single port
$ skos describe --ports       # list all known ports (installed + available)

skos install

Install one or more capability adapters into the current profile. Capabilities wire into each other automatically via shared open standards.

$ skos install capauth        # install a single port
$ skos install capauth skmemory skchat skfence skmon   # install multiple
$ skos install --dry-run capauth   # preview without applying
$ skos install --list         # list installable capabilities

05 Contribute / Extend

Add an adapter to an existing port

An adapter is a directory under v2/<C>/<port>/adapters/<name>/ containing:

• adapter.yaml — name, description, port it satisfies, open standard it speaks, license, swap-compatibility list.
• compose.yaml (or helm/ or k8s/) — the deployment manifest for this runtime.
• skos-hooks.sh — optional lifecycle hooks: pre-install, post-install, health-check, migrate-from.
• README.md — one page: what it is, why choose it over the default, any caveats.

The adapter.yaml schema (minimum):

name: garage
port: skobject
standard: s3-api
license: AGPL-3.0
swap_compatible_with: [minio, seaweedfs]
description: |
  Single-binary object store with S3-compatible API.
  Sovereign default for skobject after MinIO was archived.

Add a new port

New ports require a capability-map spec first — open a GitHub issue with the template. The spec must define: port name, which of the 4 C's it belongs to, the open standard it speaks, at least one sovereign default adapter, and any critical gaps it closes.

Adopted ports in v2 (so far): capauth · sksso · sksec · skwaf · skca · skvault · skdata · skcache · skobject · skfiles · skmodel · skflow · skmon · skpulse · skbackup · skfence · skmesh · skdns · skcicd · skinfra · skdweb · skchat · skvoice · skcomms · skbus

Dev workflow

$ git clone https://github.com/smilinTux/skos
$ cd skos
# create your adapter directory
$ mkdir -p v2/compute/skobject/adapters/garage
# add adapter.yaml + compose.yaml + README.md
$ skos describe --validate v2/compute/skobject/adapters/garage
$ git checkout -b feat/skobject-garage-adapter
$ git commit -m "feat(skobject): add Garage adapter (MinIO replacement)"
# open a PR — CI runs schema validation + install smoke test