AIppliance-Magic-Stick

Reusable public template for building an AI Appliance from an empty machine to a running AI platform.

This repository intentionally contains generic template code, public-safe defaults, render-only examples, and placeholders. Real deployment values are supplied at install time, through runtime settings, or through runtime CRs created by the dashboard.

Layout

.
├── magic-installer/            # reusable cloud-init/autoinstall template
├── magic-host/                 # reusable Ansible playbooks and roles
├── magic-cluster/              # reusable Kubernetes, app, platform and Flux bases
├── examples/demo/              # render-only public overlay using example.local values
├── .codex/skills/              # optional repo-local Codex skill sources
├── docs/
│   ├── .nojekyll
│   ├── index.html
│   ├── README.md
│   ├── architecture.md
│   ├── authentication.md
│   ├── appliance-crd.md
│   ├── configuration.md
│   ├── dashboard.md
│   ├── development.md
│   ├── getting-started.md
│   ├── gitops-overlays.md
│   ├── legal-notice.html
│   ├── modules.md
│   ├── model-catalog.md
│   ├── operator-orchestration.md
│   ├── operations.md
│   ├── privacy.html
│   └── public-release-checklist.md
├── CONTRIBUTING.md
├── SUPPORT.md
├── SECURITY.md
├── CODE_OF_CONDUCT.md
├── GOVERNANCE.md
├── MAINTAINERS.md
├── CHANGELOG.md
├── ROADMAP.md
├── THIRD_PARTY_NOTICES.md
├── LICENSE
├── AGENTS.md
└── .gitleaks.toml

Use example.local, example.com, CHANGEME, or documented variables for all template values.

Documentation

Start with docs/README.md for the full documentation index. The GitHub Pages landing page lives at docs/index.html; configure Pages to publish from the docs/ directory for a buildless project site.

Topic	Document
Installation on hardware, VMs, or Kubernetes	docs/installation/README.md
Configuration after installation	docs/installation/after-installation-dashboard.md
First checkout and installer flow	docs/getting-started.md
Repository and cluster architecture	docs/architecture.md
Local authentication and enterprise SSO	docs/authentication.md
Appliance CRD	docs/appliance-crd.md
Dashboard UI/API	docs/dashboard.md
Module catalog	docs/modules.md
Operator orchestration	docs/operator-orchestration.md
Runtime variables and secrets	docs/configuration.md
Optional GitOps overlays	docs/gitops-overlays.md
Cluster operations	docs/operations.md
AI model catalog	docs/model-catalog.md
Paperclip agent execution	docs/paperclip-agents.md
Development and release checks	docs/development.md

Agent-specific repo instructions live in AGENTS.md. Optional repo-local Codex skill sources live under .codex/skills.

Community And Security

• CONTRIBUTING.md explains the public repository boundary, validation commands, and pull request expectations.
• SECURITY.md defines how to report suspected vulnerabilities or leaked credentials without exposing deployment-specific details.
• CODE_OF_CONDUCT.md sets collaboration expectations.
• SUPPORT.md explains where to ask public questions and where not to put deployment-specific data.
• GOVERNANCE.md, MAINTAINERS.md, and CHANGELOG.md document the lightweight public project process.
• ROADMAP.md lists likely public project directions.
• THIRD_PARTY_NOTICES.md lists referenced runtime images and Helm charts for release review.

GitOps Entry Points

Public template:

kubectl kustomize magic-cluster/flux/entrypoints/base

Render-only demo overlay:

kubectl kustomize examples/demo/infra-cluster/flux-bootstrap

Public single-node profile:

kubectl kustomize magic-cluster/flux/entrypoints/single-node

Advanced deployments that use an external GitOps repository can include this repository into their source artifact, for example:

include:
  - repository:
      name: magicstick-public
    fromPath: .
    toPath: vendor/magicstick

Deployment overlays can then import individual module bases from vendor/magicstick/magic-cluster/platform/... and vendor/magicstick/magic-cluster/apps/....

Host Bootstrap

The installer writes /etc/default/ai-appliance-repo. In the default readonly-public mode, that file only needs the public Flux source and runtime settings:

• FLUX_BOOTSTRAP_MODE
• FLUX_PUBLIC_SYNC_PATH
• MAGICSTICK_PUBLIC_REPO
• MAGICSTICK_PUBLIC_REF
• MAGICSTICK_PUBLIC_REF_KIND
• AI_APPLIANCE_DOMAIN
• AI_APPLIANCE_DASHBOARD_HOST
• AI_APPLIANCE_MDNS_DOMAIN
• AI_APPLIANCE_MDNS_NAME
• AI_APPLIANCE_DASHBOARD_MDNS_NAME

The host converge runner supplies defaults for the public checkout, inventory and playbook paths. Optional GitHub bootstrap mode additionally uses:

• GIT_OWNER
• GIT_REPO
• GIT_BRANCH
• FLUX_CLUSTER_PATH
• AI_APPLIANCE_PRIVATE_CHECKOUT
• FLUX_GITHUB_TOKEN

Secrets such as Flux tokens must be supplied at install/runtime and must not be committed. In readonly-public mode Flux reads only this public repository and does not need a Git token.

The generated AI model catalog honors AI_APPLIANCE_DEFAULT_CHAT_MODEL and AI_APPLIANCE_DEFAULT_EMBEDDING_MODEL when runtime settings override the public defaults. App-specific storage and preferred model settings are runtime AppInstance.spec.values; instance hostnames are derived as <instance-name>.<instance-type>.<domain>. Module storage values are runtime ModuleActivation.spec.parameters.

See docs/model-catalog.md for the model catalog contract, external model schema, generated ConfigMap keys, and operational checks.

Appliance Modules

The base installation now includes the Appliance CRD, ModuleActivation and AppInstance CRDs, a public-safe module catalog, a default Appliance/local resource, and a live magicstick-operator controller. Optional capabilities are selected declaratively through runtime CRs. The Magic Stick Operator is a meta-operator: it enables modules with Flux and creates custom resources for specialized operators, while OpenClaw, Hermes, Paperclip, and KubeOpenCode remain responsible for their own workloads.

The default appliance is GPU-neutral: LiteLLM and the model catalog support external providers without NVIDIA hardware. The first enabled local model installs the NVIDIA GPU Operator and KubeAI on demand; it remains in WaitingForGPU until Kubernetes exposes an allocatable NVIDIA GPU.

The dashboard is the UI and API client for this model. It reads the Appliance, module catalog, Flux, Pod, Service, Ingress, and Event status, and creates or patches only ModuleActivation, ModelActivation, and AppInstance CRs when users enable modules, add models, or request instances. Appliance/local.spec remains Git-owned.

See docs/appliance-crd.md, docs/dashboard.md, docs/modules.md, and docs/operator-orchestration.md.

Validation

ANSIBLE_ROLES_PATH=magic-host/roles \
  ansible-playbook --syntax-check magic-host/playbooks/local.yml

gitleaks detect --source . --config .gitleaks.toml --no-git --redact
gitleaks detect --source . --config .gitleaks.toml --redact

kubectl kustomize magic-cluster/flux/entrypoints/base
kubectl kustomize magic-cluster/flux/entrypoints/single-node
kubectl kustomize magic-cluster/apps/dashboard
kubectl kustomize magic-cluster/platform/magicstick-operator
kubectl kustomize magic-cluster/platform/basis
kubectl kustomize magic-cluster/platform/gpu
kubectl kustomize magic-cluster/platform/ai/kubeai
kubectl kustomize magic-cluster/platform/ai/hermes-operator
kubectl kustomize magic-cluster/platform/ai/openclaw-operator
kubectl kustomize magic-cluster/platform/ai/paperclip-operator
kubectl kustomize magic-cluster/platform/ai/agent-sandbox
kubectl kustomize magic-cluster/apps/ai/litellm/base
kubectl kustomize magic-cluster/apps/ai/model-catalog
kubectl kustomize magic-cluster/apps/ai/anything-llm/base
kubectl kustomize magic-cluster/apps/ai/kubeopencode
kubectl kustomize examples/demo/infra-cluster/flux-bootstrap

See docs/public-release-checklist.md before publishing a release tag.