OCI-native provider package runtime, lazy workspace shell, and packager.
kiox packages tools and toolchains as OCI artifacts, installs them into a shared cache, and exposes them through reproducible workspace shims. The current architecture normalizes both legacy single-binary manifests and newer provider packages that declare multiple tools, bundles, assets, and environments.
The main abstractions are:
- Workspace: the unit of execution
- Provider package: the unit of distribution
- Tool: an executable surface exposed by a provider
- Runtime plugin: the resolution and execution strategy for a tool (
oci,script, orlocal)
Workspace state follows a simple desired-vs-actual split:
kiox.yaml: user-owned desired workspace statekiox.lock: kiox-owned resolved provider state
- Start with the concept-first landing page: website/docs/intro.md
- Run the local docs site:
cd website && npm install && npm run docs:start - Build the static docs site:
cd website && npm run docs:build - Local provider fixture commands live in
TEST_PROVIDERS.md
The docs site builds into website/docs-build/. To publish it manually to Cloudflare Pages:
cd website
npm ci
npm run docs:build
wrangler login
wrangler pages deploy docs-build --project-name kioxReplace kiox with your Cloudflare Pages project name if it is different.
Install from source:
go install github.com/sourceplane/kiox/cmd/kiox@latestOr install a release binary:
curl -fsSL https://raw.githubusercontent.com/sourceplane/kiox/main/install.sh | bashVerify the CLI:
kiox version
kiox --helpBuild kiox and package the normalized multi-tool fixture:
make build
./bin/kiox release \
--manifest testdata/multi-tool-provider/provider.yaml \
--dist testdata/multi-tool-provider/dist \
--output testdata/multi-tool-provider/ociCreate a workspace from the local OCI layout and run both the provider alias and the provided tool command:
./bin/kiox init demo -p testdata/multi-tool-provider/oci as echo
./bin/kiox --workspace demo status
./bin/kiox --workspace demo exec echo one two
./bin/kiox --workspace demo exec echo-tool alpha betaThe first execution materializes the bundled setup-echo tool and lazy-installs the script-backed echo-tool into the provider store.
Create and use a workspace:
kiox init demo
kiox add core/node as node
kiox sync
kiox use demoAdd providers and run them through the workspace shell:
kiox provider add core/node as node
kiox provider add sourceplane/lite-ci as lite-ci
kiox -- node build
kiox -- lite-ci planPackage and publish a provider:
kiox release --manifest provider.yaml --main ./cmd/my-provider --push ghcr.io/acme/my-provider:v1.2.3make test
go test ./...
cd website && npm run docs:buildFor manual smoke tests against the repository fixtures, see TEST_PROVIDERS.md.