{"id":49371800,"url":"https://github.com/mmonteleone/corral","last_synced_at":"2026-04-28T00:01:21.565Z","repository":{"id":350360765,"uuid":"1206482552","full_name":"mmonteleone/corral","owner":"mmonteleone","description":"Ollama-shaped llama.cpp, MLX, and model management helper","archived":false,"fork":false,"pushed_at":"2026-04-17T20:40:07.000Z","size":183,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-17T22:36:00.194Z","etag":null,"topics":["cli","gemma","gguf","huggingface","lamma","llm","llms","local-llm","ollama","phi","qwen","shell"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mmonteleone.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":null,"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-04-10T00:49:11.000Z","updated_at":"2026-04-17T21:38:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mmonteleone/corral","commit_stats":null,"previous_names":["mmonteleone/yallama","mmonteleone/corral"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/mmonteleone/corral","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmonteleone%2Fcorral","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmonteleone%2Fcorral/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmonteleone%2Fcorral/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmonteleone%2Fcorral/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mmonteleone","download_url":"https://codeload.github.com/mmonteleone/corral/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmonteleone%2Fcorral/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32360116,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-27T20:07:02.737Z","status":"ssl_error","status_checked_at":"2026-04-27T20:07:00.910Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["cli","gemma","gguf","huggingface","lamma","llm","llms","local-llm","ollama","phi","qwen","shell"],"created_at":"2026-04-28T00:00:53.444Z","updated_at":"2026-04-28T00:01:21.508Z","avatar_url":"https://github.com/mmonteleone.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Corral ✨🦙\n\nRun local models with the ease of [Ollama](https://ollama.com) and full power of official [llama.cpp](https://github.com/ggml-org/llama.cpp) releases and [MLX](https://github.com/ml-explore/mlx-lm) on Apple Silicon.\n\n**Corral is just a shell script**. It installs and updates official latest llama.cpp and MLX releases, uses the standard Hugging Face registry for models, and provides an Ollama-style CLI for running and managing local models: *search*, *pull*, *run*, *serve*, *launch*, *list*, *remove*, *update*, etc. along with templated usage profiles and tool launchers.\n\n```sh\ncorral search gemma\ncorral run unsloth/gemma-4-26B-A4B-it-GGUF\ncorral launch pi\n```\n\n## Why Corral?\n\n- Upstream, official llama.cpp and MLX builds, with their latest performance benefits and model support (*ahem*, [Gemma 4](https://deepmind.google/models/gemma/gemma-4/)) vs downstream integrations and forks\n- Ollama-style ergonomics for running *and* managing local models, without an always-on daemon\n- The full Hugging Face model registry, not just what Ollama ships\n- Model search and discovery against Hugging Face from the command line\n- Saved, templated, profiles for pinning a model with a specific set of flags\n- Pre-configured launcher for tools including [OpenCode](https://opencode.ai) and [Pi](https://pi.dev)\n- Command, model, profile, and quant shell completions for fish, zsh, and bash\n- Standard HF cache. Downloaded models are visible to other tools\n\n## Does the world really need this?\n\nNot really.\n\n## Install\n\n```sh\n# System-wide\nsudo curl -fsSL https://github.com/mmonteleone/corral/releases/latest/download/corral \\\n  -o /usr/local/bin/corral \u0026\u0026 sudo chmod +x /usr/local/bin/corral\n\n# Or user-local (no sudo)\ncurl -fsSL https://github.com/mmonteleone/corral/releases/latest/download/corral \\\n  -o ~/.local/bin/corral \u0026\u0026 chmod +x ~/.local/bin/corral\n```\n\n\u003e [!NOTE]\n\u003e `~/.local/bin` may not be in `$PATH` by default on macOS. Add it: `export PATH=\"$HOME/.local/bin:$PATH\"`\n\nThen install a backend and set up shell completions:\n\n```sh\ncorral install\n```\n\nOn Apple Silicon this installs **both** llama.cpp (`llama-cli`, `llama-server`) and MLX (`mlx-lm`). On other platforms, llama.cpp only. Restrict with `--backend llama.cpp` or `--backend mlx`.\n\n`corral install` downloads the latest official llama.cpp release and, after prompting, adds it to `$PATH` and installs shell completions. Pass `--shell-profile` to accept automatically, or `--no-shell-profile` to skip. For MLX, corral installs `mlx-lm` via `uv` (offering to install `uv` via Homebrew if needed).\n\n## Quick start\n\n```sh\ncorral search gemma                           # Find models on Hugging Face\ncorral run unsloth/gemma-4-26B-A4B-it-GGUF    # Chat (downloads on first use)\ncorral run mlx-community/gemma-4-26b-a4b-it-6bit  # MLX model (auto-detected)\ncorral serve unsloth/gemma-4-26B-A4B-it-GGUF  # OpenAI-compatible API + web UI\n\ncorral run unsloth/gemma-4-26B-A4B-it-GGUF -- -ngl 999 -c 8192  # Extra flags\n\n# Profiles: save a name + model + flags combo\ncorral profile set coder unsloth/gemma-4-26B-A4B-it-GGUF -- \\\n  --ctx-size 65536 --temp 0.2 -ngl 999\ncorral run coder\n\n# Or seed a profile from a built-in template\ncorral profile set mycoder code unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q4_K_M\ncorral run mycoder\n\n# Launch supported coding harnesses against a running server\ncorral launch pi\ncorral launch opencode\n\ncorral list                                  # Models, profiles, templates\ncorral remove unsloth/gemma-4-26B-A4B-it-GGUF\ncorral remove coder\n```\n\n## Commands\n\n| Command | Description |\n|---|---|\n| `install` | Install backend(s) and shell completions |\n| `run MODEL\\|PROFILE` | Interactive chat (`llama-cli` / `mlx_lm.chat`) |\n| `serve MODEL\\|PROFILE` | OpenAI-compatible server (`llama-server` / `mlx_lm.server`) |\n| `launch TOOL` | Configure and launch `pi` or `opencode` against a running server |\n| `pull MODEL` | Download model artifacts without running |\n| `search [QUERY]` | Search Hugging Face for compatible models |\n| `browse MODEL` | Open a model's Hugging Face page in the browser |\n| `list` / `ls` | List cached models, profiles, and templates |\n| `remove` / `rm` | Remove cached models or profiles |\n| `profile set\\|show\\|duplicate` | Manage saved profiles |\n| `template show\\|set\\|remove` | Manage flag templates |\n| `status` | Platform info and installed backend status |\n| `update` | Update backends to latest versions |\n| `versions` | Show installed backend versions |\n| `prune` | Remove old llama.cpp installs (keeps current) |\n| `uninstall` | Remove backends and optionally clean up caches |\n| `ps` | Show running model processes |\n| `version` | Show the corral version |\n\nRun `corral \u003ccommand\u003e --help` for per-command flags.\n\n## Models and quants\n\nModels use standard Hugging Face `USER/MODEL` IDs. For llama.cpp, append `:QUANT` to pin a quantization:\n\n```sh\ncorral run unsloth/gemma-4-26B-A4B-it-GGUF            # default quant\ncorral run unsloth/gemma-4-26B-A4B-it-GGUF:UD-Q6_K    # specific quant\n```\n\nMLX models use plain IDs without `:QUANT` (e.g. `mlx-community/gemma-4-26b-a4b-it-6bit`).\n\nAll models are stored in the standard Hugging Face cache (`~/.cache/huggingface/hub/`).\n\n### Search\n\n```sh\ncorral search --backend llama.cpp gemma            # GGUF-tagged results\ncorral search --backend mlx gemma                  # MLX-tagged results\ncorral search --backend llama.cpp qwen --quants    # show GGUF quant variants\n```\n\n### List and remove\n\n```sh\ncorral list                     # all models, profiles, templates\ncorral ls --models              # only models\ncorral ls --backend mlx         # only MLX models\ncorral remove USER/MODEL:QUANT  # remove one quant (llama.cpp)\ncorral remove USER/MODEL        # remove entire model\ncorral remove PROFILE_NAME      # remove a profile\n```\n\n## Profiles and templates\n\nA **profile** saves a model + flags under a name, usable anywhere a model is accepted:\n\n```sh\ncorral profile set coder unsloth/gemma-4-26B-A4B-it-GGUF -- \\\n  --ctx-size 65536 --temp 0.2 -ngl 999\n\ncorral run coder\ncorral serve coder\ncorral run coder -- --temp 0.5   # inline flags override profile flags\n```\n\nA **template** is a reusable set of flags that can seed profiles. Corral ships two:\n\n| Template | Purpose | Key flags |\n|---|---|---|\n| `chat` | Conversational | `--temp 0.8` |\n| `code` | Coding | `--temp 0.2` |\n\n```sh\ncorral profile set mycoder code unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q4_K_M   # from template\ncorral run mycoder\n```\n\nCreate custom templates with `corral template set`. If a template includes a `model=` line, the model is optional when creating profiles from it:\n\n```sh\ncorral template set work-chat user/our-llm:Q4_K -- --temp 0.6 --ctx-size 16384\ncorral profile set alice-chat work-chat          # model comes from template\ncorral profile set test-chat work-chat user/new-llm:Q4_K  # override model\n```\n\n```sh\ncorral profile show coder            # inspect\ncorral profile duplicate coder coder2\ncorral template show code\ncorral template remove work-chat     # delete user template\n```\n\n### Profile file format\n\nProfiles are plain text in `~/.config/corral/profiles/` with a `model=` line and flags (one per line). Section headers scope flags to a backend, command, or both:\n\n```\nmodel=unsloth/gemma-4-26B-A4B-it-GGUF\n--temp 0.2\n\n[mlx]\n--max-tokens 4096\n\n[mlx.serve]\n--top-k 20\n\n[llama.cpp]\n--top-k 20\n--repeat-penalty 1.05\n--ctx-size 65536\n--n-predict 4096\n--flash-attn on\n-ngl 999\n\n[llama.cpp.serve]\n--cache-reuse 256\n\n```\n\n| Section | Scope |\n|---|---|\n| *(none)* | All backends and commands |\n| `[run]` / `[serve]` | One command, any backend |\n| `[llama.cpp]` / `[mlx]` | One backend, any command |\n| `[llama.cpp.run]` / `[llama.cpp.serve]` / `[mlx.run]` / `[mlx.serve]` | One backend + one command |\n\n`profile set` creates flat profiles. Section headers are added by editing the file directly or inherited from templates. Templates use the same format (`model=` optional) and live in `~/.config/corral/templates/`. A user-defined template with the same name as a built-in takes precedence.\n\n## Launch coding harnesses\n\n`corral launch` configures a supported coding harness to use a currently running `corral serve` instance, then launches the harness.\n\nSupported harnesses currently include `pi` and `opencode`. Corral inspects running servers via `corral ps`, matches the server's local OpenAI-compatible endpoint and model name, and writes that into the harness config. Existing configs are preserved with a timestamped backup next to any modified config file\n\n## Shell completions\n\nCompletions for commands, models, quants, and profiles are available for **fish**, **zsh**, and **bash**. They install automatically during `corral install` when shell profile edits are accepted. To add them later:\n\n```sh\ncorral install --shell-profile\n```\n\n## Configuration\n\n| Variable | Purpose |\n|---|---|\n| `CORRAL_INSTALL_ROOT` | Override llama.cpp install directory |\n| `CORRAL_PROFILES_DIR` | Override profiles directory (default: `~/.config/corral/profiles`) |\n| `CORRAL_TEMPLATES_DIR` | Override templates directory (default: `~/.config/corral/templates`) |\n| `HF_TOKEN` | Authenticate for private/gated HF models (`HF_HUB_TOKEN` and `HUGGING_FACE_HUB_TOKEN` also work) |\n\n## Uninstall\n\n```sh\ncorral uninstall --self                      # remove all backends + corral itself\ncorral uninstall --backend mlx               # remove one backend\ncorral uninstall --self --delete-hf-cache    # also wipe downloaded models\n```\n\nAll uninstall commands prompt for confirmation. Add `--force` to skip.\n\n## Compatibility\n\n| | Platforms |\n|---|---|\n| **llama.cpp** | macOS arm64/x86_64, Linux x86_64/arm64 |\n| **MLX** | macOS arm64 only (Apple Silicon) |\n\nRequires `curl`, `tar`, `jq`, and standard POSIX tools. MLX operations require `uv`. Shell completions support fish, zsh, and bash. `install` and `update` are atomic. `remove` refuses to delete models currently in use.\n\n## Development\n\nSource entry point is [src/corral.sh](src/corral.sh) with modules in [src/lib/](src/lib/). The standalone distributable is built by [tools/build.sh](tools/build.sh), which inlines modules and stamps the version from the current git tag.\n\nCurrent module split is feature-oriented: helpers, cache, profiles, shell integration, runtime lifecycle, process discovery, inventory/removal, launch, search, and completions.\n\nWithin that split, public cross-module helpers are named without a leading underscore; underscore-prefixed helpers are intended to stay private to their defining module.\n\n```sh\nbash tools/build.sh              # build standalone artifact\nshellcheck src/corral.sh src/lib/*.sh   # lint\nbash tests/unit.sh               # full unit suite\nbash tests/smoke.sh              # full smoke suite\n```\n\n```sh\nbash tests/unit.sh test_parse_model_spec_without_quant  # single unit test\nbash tests/smoke.sh test_search_returns_results         # single smoke test\n```\n\n`dist/corral` is generated output. Edit `src/corral.sh`, `src/lib/*.sh`, `src/templates/*.conf`, `src/launch/*.tmpl`, or `src/jq/search-quants.jq`, then rebuild.\n\n## License\n\nMIT License. Copyright (c) 2026 Michael Monteleone.\n\nCorral is not affiliated with [Ollama](https://ollama.com), [llama.cpp](https://github.com/ggml-org/llama.cpp), [MLX](https://github.com/ml-explore/mlx-lm), or [Hugging Face](https://huggingface.co).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmmonteleone%2Fcorral","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmmonteleone%2Fcorral","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmmonteleone%2Fcorral/lists"}