oinc

  ^..^
 ( oo )  oinc ~ OKD in a container
  (..)

MicroShift under the hood, with Console, OLM, and ConsolePlugin CRD out of the box.

Warning

This project is largely the product of coffee and vibe coding. It works, but set your expectations accordingly.

oinc create

That's it. You get a single-node cluster with the OpenShift Console on localhost:9000, OLM running, and the ConsolePlugin CRD available -- close enough to real OCP for local dev work.

Features

• Auto-detects container runtime (docker, podman) -- no flags needed
• Version switching -- oinc create --version 4.20 to target a specific OCP release
• Console included -- OpenShift Console runs as a sidecar, no separate setup
• OLM included -- baked into the image, operator workflows work out of the box
• Addon system -- layer on Gateway API, cert-manager, MetalLB, Istio, Kuadrant as needed
• Console plugin support -- --console-plugin "my-plugin=http://localhost:9001" for plugin dev
• Interactive TUI -- step-by-step progress with spinners, interactive addon picker, live status dashboard

Supported versions

OCP	MicroShift	Console	Architectures
4.22 (default)	4.22.0-okd-scos.ec.16	4.22	amd64, arm64
4.21	4.21.0-okd-scos.ec.15	4.21	amd64, arm64
4.20	4.20.0-okd-scos.16	4.20	amd64, arm64

Use /add-version in Claude Code to add a new version, or see docs/images.md for the manual process.

Install

Download a binary from releases:

# macOS (Apple Silicon)
curl -L https://github.com/jasonmadigan/oinc/releases/latest/download/oinc-darwin-arm64 -o oinc
chmod +x oinc && sudo mv oinc /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/jasonmadigan/oinc/releases/latest/download/oinc-darwin-amd64 -o oinc
chmod +x oinc && sudo mv oinc /usr/local/bin/

# Linux (amd64)
curl -L https://github.com/jasonmadigan/oinc/releases/latest/download/oinc-linux-amd64 -o oinc
chmod +x oinc && sudo mv oinc /usr/local/bin/

Or with Go:

go install github.com/jasonmadigan/oinc/cmd/oinc@latest

Quick start

# create cluster (latest OCP version, auto-detect runtime)
oinc create

# create with a specific version
oinc create --version 4.20

# create with addons
oinc create --addons gateway-api,cert-manager

# addon version pinning
oinc create --addons cert-manager@1.16.0,metallb@0.14.8

# wire in a console plugin dev server
oinc create --console-plugin "my-plugin=http://host.docker.internal:9001"

# after the plugin operator creates a ConsolePlugin with service proxies,
# restart the standalone dev Console with those proxies
oinc console sync-plugin-proxy my-plugin \
  --console-plugin "my-plugin=http://host.docker.internal:9001"

# cluster status
oinc status

# interactive status dashboard
oinc status --watch

# fetch/refresh kubeconfig
oinc kubeconfig

# load a locally built image into the cluster
oinc load-image localhost/my-image:dev

# switch OCP version (delete + create)
oinc switch 4.20

# list available versions
oinc version list

# tear down
oinc delete

CLI

Commands show styled progress in a terminal (spinners, checkmarks, boxed output) and fall back to plain log output when piped or in CI.

• oinc create -- step-by-step progress with a summary of endpoints on completion
• oinc delete -- confirmation prompt (skip with --force)
• oinc status -- boxed endpoint and addon status; --watch for a live-updating dashboard with pod listing
• oinc addon install -- interactive picker when run with no arguments; shows installed addons as checked
• oinc addon install kuadrant -- step progress with live sub-status per addon
• oinc status -o json -- machine-readable output for scripting

Addons

The base cluster includes MicroShift + OLM + Console + ConsolePlugin CRD. Addons layer extra infrastructure on top:

Addon	What it provides	Install method
gateway-api	Kubernetes Gateway API CRDs	upstream CRDs (k8s client)
cert-manager	Certificate management	upstream manifests (kubectl)
metallb	LoadBalancer IP allocation	upstream manifests (kubectl)
istio	Istio service mesh via Sail operator	helm
kuadrant	API management (rate limiting, auth, DNS)	helm
rhdh	Red Hat Developer Hub (Backstage)	helm
mcp-gateway	MCP Gateway (AI tool gateway)	helm (OCI)

Dependencies are resolved automatically. Installing kuadrant will pull in gateway-api, cert-manager, metallb, and istio. Installing mcp-gateway will pull in kuadrant and all its dependencies.

# at create time
oinc create --addons kuadrant

# or post-hoc (interactive picker)
oinc addon install

# or specify directly
oinc addon install gateway-api
oinc addon list

Pin addon versions with @:

oinc addon install cert-manager@1.16.0

Instance options

Opt-in flags make the addons create the instances a working cluster needs, on top of the operators and CRDs they already install:

# --kuadrant-devportal: enable the developer portal on the Kuadrant CR
# --metallb-address-pool: IPAddressPool + L2Advertisement (auto-derived range)
# --gateway-api-gateway: default Gateway (kuadrant-ingressgateway, istio class), waits for Programmed
oinc create --addons kuadrant@latest \
  --kuadrant-devportal \
  --metallb-address-pool auto \
  --gateway-api-gateway

--metallb-address-pool also takes an explicit range (172.17.0.200-172.17.0.220) or CIDR. Defaults are unchanged: without the flags the addons behave exactly as before. See docs/addons.md for the mechanics (portal field verification, gateway address via the class-scoped metallb).

RHDH

The rhdh addon installs Red Hat Developer Hub with guest auth enabled and exposes it via a Route on the ingress HTTP port. With default ports it is reachable at http://rhdh.127.0.0.1.nip.io:9080 (no port-forward needed).

oinc create --addons rhdh

# pin the chart version (rhdh@latest follows the chart index)
oinc create --addons rhdh@6.2.2

# custom image (e.g. sideloaded via oinc load-image), values overlay, quickstart off
oinc create --addons rhdh \
  --rhdh-image localhost/my-rhdh:dev \
  --rhdh-values overlay.yaml \
  --rhdh-disable-quickstart

--rhdh-values merges a helm values overlay into the chart install, for dynamic-plugins config and app-config extras. See docs/addons.md for the full option reference and the MicroShift-specific overrides the addon applies.

Kubeconfig

oinc create automatically merges the cluster kubeconfig into ~/.kube/config with context name oinc. If you need to refresh it:

# merge into ~/.kube/config
oinc kubeconfig

# print raw kubeconfig to stdout
oinc kubeconfig --print

# switch to oinc context
kubectl config use-context oinc

Loading local images

oinc load-image streams a locally built image into the cluster's CRI-O store, the kind load docker-image equivalent. Pods can then use it with imagePullPolicy: IfNotPresent and no registry.

docker build -t localhost/my-image:dev .
oinc load-image localhost/my-image:dev

The ref is preserved exactly, so localhost/<name>:<tag> refs resolve as given. Re-running with the same ref succeeds. Works with docker or podman as the host runtime; the command picks whichever one owns the running cluster.

Console plugin service proxies

On a real OpenShift cluster, the Console operator translates a dynamic plugin's ConsolePlugin.spec.proxy entries into Bridge configuration. OINC runs its Console as a standalone development container, so it does not have that reconciliation layer.

After installing or rebuilding an operator that reconciles service proxies, run:

oinc console sync-plugin-proxy <ConsolePlugin-name> \
  --console-plugin "<plugin-name>=http://host.docker.internal:<dev-server-port>"

The command reads ConsolePlugin.spec.proxy, creates OINC-only LoadBalancer shadow Services so the Console container can reach the in-cluster backends, mounts the OpenShift service CA, and restarts the standalone Console. It does not change the product deployment contract: the plugin operator remains the source of truth for the backend Service and ConsolePlugin resource. The metallb addon must have an address pool; --metallb-address-pool auto is the simplest development setup. Reload the browser after the Console restarts.

Ports

Port	Service
6443	Kubernetes API server
9000	OpenShift Console
9080	Ingress HTTP (Routes, Gateway API)
9443	Ingress HTTPS (Routes, Gateway API)

Requirements

• Docker or Podman
• ~4GB RAM available for the container
• curl (for fetching upstream manifests and CRDs)
• kubectl (for cert-manager and metallb addons)
• helm (for istio, kuadrant, rhdh and mcp-gateway addons)

Acknowledgements

oinc builds on the work of several projects:

• MicroShift -- the lightweight OpenShift runtime that powers the cluster
• microshift-io -- OKD-flavoured MicroShift builds and pre-built RPMs
• OKD -- the community distribution of Kubernetes that powers OpenShift
• OpenShift Console -- the web UI
• minc -- inspiration for running MicroShift in a container