{"id":51118676,"url":"https://github.com/defilantech/llmkube-bootstrap","last_synced_at":"2026-06-25T00:01:16.094Z","repository":{"id":359285757,"uuid":"1245366991","full_name":"defilantech/llmkube-bootstrap","owner":"defilantech","description":"One-command setup for a fresh Apple Silicon Mac to run local LLM inference on LLMKube.","archived":false,"fork":false,"pushed_at":"2026-05-21T07:19:09.000Z","size":32,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-21T13:40:45.194Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/defilantech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-21T06:47:02.000Z","updated_at":"2026-05-21T07:19:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/defilantech/llmkube-bootstrap","commit_stats":null,"previous_names":["defilantech/llmkube-bootstrap"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/defilantech/llmkube-bootstrap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/defilantech%2Fllmkube-bootstrap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/defilantech%2Fllmkube-bootstrap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/defilantech%2Fllmkube-bootstrap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/defilantech%2Fllmkube-bootstrap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/defilantech","download_url":"https://codeload.github.com/defilantech/llmkube-bootstrap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/defilantech%2Fllmkube-bootstrap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34753781,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-25T00:01:15.000Z","updated_at":"2026-06-25T00:01:16.063Z","avatar_url":"https://github.com/defilantech.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# llmkube-bootstrap\n\nSetup script + Ansible playbook that gets a fresh Apple Silicon\nMacBook Pro from out-of-the-box to running local LLM inference on\n[LLMKube](https://github.com/defilantech/LLMKube). One command, then\nthe secrets you wire in yourself.\n\nTarget: Apple Silicon MacBook Pro on macOS Sequoia (15) or later.\nThe default memory budget is tuned for a 128 GB machine; on smaller\nhardware, lower `metal_agent_memory_fraction` in `group_vars/all.yml`\nbefore running bootstrap. Earlier macOS versions and Intel Macs are\nintentionally out of scope for v0.1.\n\n## What it sets up\n\nAfter a clean bootstrap you have:\n\n- Homebrew + the LLMKube-supporting package set (`kubectl`, `helm`,\n  `kind`, `jq`, `yq`, `gh`, `k9s`, `tmux`, `ripgrep`, `fzf`).\n- `colima` started with a user-space Lima VM (4 CPU, 6 GiB, 60 GiB\n  disk by default; override via `--extra-vars`). Provides the Docker\n  socket `kind` uses. `docker` / `docker-compose` / `docker-buildx`\n  CLIs installed via Homebrew, no Docker Desktop required. To use\n  Docker Desktop instead, see the \"Docker Desktop on Apple Silicon\"\n  callout near the end of this README.\n- A `kind` cluster named `llmkube-local` running the LLMKube\n  operator from the published Helm chart.\n- A clone of `defilantech/LLMKube` at `~/src/LLMKube`, and the\n  `metal-agent` daemon installed + running under `launchd`.\n- A starter model (`phi-4-mini-instruct`, Q4_K_M) deployed via\n  `Model` + `InferenceService` CRs and verified via a real chat\n  completion against `localhost:\u003cport\u003e`.\n- `opencode` installed with a sanitized config pointing at your local\n  llama-server. MCP servers (`brave-search`, `github`, `context7`,\n  `playwright`) are configured but inert until you supply API keys.\n\nOptional add-ons via flags:\n\n- `--with-carnice` — pulls\n  `Carnice-Qwen3.6-MoE-35B-A3B-APEX-MTP-I-Balanced.gguf` (~36 GB) and\n  deploys it as a second InferenceService. A larger MoE coder model\n  serving up to 256 K context via YaRN; expect 10–40 min to download\n  depending on connection.\n- `--with-foreman` — installs the Foreman agentic-workload add-on\n  (operator + node agent) onto the local kind cluster. See the\n  [LLMKube Foreman M3 runbook](https://github.com/defilantech/LLMKube/blob/main/docs/foreman/runbook-m3.md).\n\n## Quickstart\n\n```bash\ngit clone https://github.com/defilantech/llmkube-bootstrap\ncd llmkube-bootstrap\n./bootstrap.sh                         # base install (phi-4-mini)\n./bootstrap.sh --with-carnice          # base + Carnice 35B\n./bootstrap.sh --with-foreman          # base + Foreman opt-in\n./bootstrap.sh --with-foreman --with-carnice   # the works\n```\n\nOn a fresh Mac, the very first `git clone` will trigger macOS to\nprompt \"git requires Command Line Tools, install?\" — click Install,\nwait ~3 min, re-run the clone. That is the only pre-prerequisite this\nrepo cannot pave around.\n\nBootstrap is idempotent. Run it again after an OS update or a chart\nrelease to bring the install current.\n\n## After bootstrap: secrets you wire in yourself\n\nThe playbook intentionally never touches secrets. After it finishes:\n\n| What | Where | Used by |\n|---|---|---|\n| GitHub PAT | `~/.config/foreman/github-token` (or `$GITHUB_TOKEN` env) | Foreman (push branches to your fork), `gh` CLI |\n| Brave Search API key | `$BRAVE_API_KEY` env (e.g. in `~/.zshrc`) | opencode's `brave-search` MCP server |\n| Anthropic API key | `$ANTHROPIC_API_KEY` env | opencode's Anthropic provider, Foreman M6 planner |\n| Hugging Face token | `$HF_TOKEN` env | opencode's `huggingface` MCP server, gated model downloads |\n| Jira creds | `$JIRA_URL` / `$JIRA_USERNAME` / `$JIRA_API_TOKEN` env | opencode's `atlassian` MCP server |\n\nRestart your shell (or `source ~/.zshrc`) after setting envs.\n\n## Teardown\n\nIf you need to start from a clean slate to test a change to the\nplaybook:\n\n```bash\n./teardown.sh                          # removes kind cluster, launchd unit, model store\n```\n\n`teardown.sh` deliberately does NOT uninstall Homebrew, Docker\nDesktop, or your shell config. It removes only what the bootstrap\ncreated in the LLMKube layer.\n\n## Repo layout\n\n```\nbootstrap.sh             # ensures brew + ansible, then runs the playbook\nteardown.sh              # nuke the LLMKube layer for re-testing\nplaybook.yml             # Ansible entrypoint\ninventory/localhost.yml  # always local\ngroup_vars/all.yml       # tunables (memory_fraction, src_dir, model_repo, etc.)\nroles/\n  system/                # macOS sanity asserts, Xcode CLT\n  homebrew/              # brew + per-package installs\n  kubernetes/            # colima, kind, kubectl, helm, k9s\n  llmkube_core/          # clone LLMKube, helm install, install metal-agent\n  model_starter/         # download phi-4-mini, apply Model + InferenceService\n  opencode/              # opencode binary + sanitized config template\n  developer_tools/       # gh, jq, yq, tmux, etc.\n  carnice/               # opt-in via --tags carnice\n  foreman/               # opt-in via --tags foreman\nfiles/\n  opencode.json.template # the opencode config we drop into ~/.config/opencode/\n.github/workflows/\n  ci.yml                 # ansible-lint + yamllint + shellcheck\n```\n\n## CI\n\nEvery PR runs three linters:\n\n- `ansible-lint` — Ansible best practices, role correctness\n- `yamllint` — YAML formatting\n- `shellcheck` — `bootstrap.sh` and `teardown.sh`\n\nThese run on an Ubuntu runner in seconds. They do not exercise the\nplaybook end-to-end — macOS-bound bugs in homebrew / launchd / colima\nwill only surface when a human runs the bootstrap on a real Mac. A\nfuture change may add a nightly macOS runner that does the\nfull install; that's not in v0.1.\n\n## Docker Desktop on Apple Silicon (opt-in only)\n\nThe default Docker runtime is **colima**. If you specifically want\nDocker Desktop instead (for the GUI, for parity with an existing\nteam setup, or to test something Docker Desktop-only), opt in via\nyour `group_vars`:\n\n```yaml\n# group_vars/all.yml or a per-host override\nhomebrew_casks:\n  - docker          # the cask is named `docker`; brew resolves to docker-desktop\n```\n\nTwo caveats specific to Apple Silicon:\n\n1. Docker Desktop's cask postinstall hook writes CLI plugin symlinks\n   into `/usr/local/cli-plugins`. The pre-task in\n   `roles/homebrew/tasks/main.yml` handles that automatically when\n   `homebrew_casks` contains `docker` / `docker-desktop`.\n2. Docker Desktop also writes the `docker`, `docker-compose`, and\n   `docker-buildx` binaries into `/usr/local/bin`. On a fresh\n   Apple Silicon Mac that directory may not exist (Homebrew lives\n   at `/opt/homebrew/bin`), and `/usr/local/` is root-owned. If\n   bootstrap fails here, run once:\n\n   ```sh\n   sudo mkdir -p /usr/local/bin\n   sudo chown -R \"$(whoami)\":staff /usr/local/bin\n   ./bootstrap.sh\n   ```\n\n   Subsequent runs no-op; Docker Desktop will not try to recreate\n   the directory once it has user-write perms.\n\nIf neither caveat sounds appealing, the default colima path is\nstrictly easier.\n\n## Contributing\n\nThis repo is small but opinionated. Two rules:\n\n1. Roles must be idempotent. Re-running `./bootstrap.sh` on a fully\n   set-up machine must converge cleanly to \"ok=N changed=0\" — no\n   destructive operations, no half-applied state.\n2. Roles must not require secrets at apply time. The secret\n   inventory in this README is the contract; if a role needs a new\n   secret, add it to the table.\n\nDCO sign-off on every commit (`git commit -s`).\n\n## License\n\nApache 2.0 — matches LLMKube's license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdefilantech%2Fllmkube-bootstrap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdefilantech%2Fllmkube-bootstrap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdefilantech%2Fllmkube-bootstrap/lists"}