{"id":43952386,"url":"https://github.com/xencon/aixcl","last_synced_at":"2026-05-03T20:10:11.270Z","repository":{"id":246255130,"uuid":"820501008","full_name":"xencon/aixcl","owner":"xencon","description":"Agentic SDLC with local LLM's.","archived":false,"fork":false,"pushed_at":"2026-04-29T21:27:07.000Z","size":2410,"stargazers_count":16,"open_issues_count":0,"forks_count":10,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-29T23:29:04.531Z","etag":null,"topics":["agentic-workflow","ai-development","development-platform","idp-platform","llamacpp","llm","local-first","ollama","opernsource","self-hosted","sldc","vllm","workflow-automation"],"latest_commit_sha":null,"homepage":"https://www.xenithconsulting.com/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xencon.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2024-06-26T15:36:59.000Z","updated_at":"2026-04-29T21:27:11.000Z","dependencies_parsed_at":"2024-06-26T22:20:25.112Z","dependency_job_id":"e46e7706-9ca6-480c-99bc-21a3ff8b7b5a","html_url":"https://github.com/xencon/aixcl","commit_stats":null,"previous_names":["xencon/aixcl"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/xencon/aixcl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xencon%2Faixcl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xencon%2Faixcl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xencon%2Faixcl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xencon%2Faixcl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xencon","download_url":"https://codeload.github.com/xencon/aixcl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xencon%2Faixcl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32456167,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T22:27:22.272Z","status":"online","status_checked_at":"2026-04-30T02:00:05.929Z","response_time":57,"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":["agentic-workflow","ai-development","development-platform","idp-platform","llamacpp","llm","local-first","ollama","opernsource","self-hosted","sldc","vllm","workflow-automation"],"created_at":"2026-02-07T04:03:02.478Z","updated_at":"2026-04-30T06:01:48.317Z","avatar_url":"https://github.com/xencon.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AIXCL\n\n**A self-hosted, local-first AI stack for running and integrating LLMs.**\n\nAIXCL provides a simple CLI, a web interface, and a containerized stack to run, manage, and integrate Large Language Models directly into your developer workflow.\n\n\u003e **New:** AIXCL now supports [Dev Containers](.devcontainer/) for a consistent, pre-configured development environment. See the [Dev Container Guide](.devcontainer/README.md) for details.\n\n## Prerequisites\n\n* **Docker \u0026 Docker Compose** installed.\n* **8 GB VRAM** (for GPU compatible LLM's). \n* **32 GB RAM** (minimum recommended).\n* **128 GB Disk Space** (for models and images).\n\n---\n\n## Quick Start\n\n**1. Clone and Verify**\n\n```bash\ngit clone https://github.com/xencon/aixcl.git \u0026\u0026 cd aixcl\n./aixcl utils check-env\n```\n\n\u003e Note: The check will warn if `hf` is missing. Install with pip or brew if you plan to use llama.cpp or vLLM engines.\n\n**2. Start the Stack**\n\n```bash\n# Choose a profile: usr (minimal), dev (UI+DB), ops (Observability), sys (Full)\n./aixcl stack start --profile usr\n```\n\n**3. Choose Your Engine**\n\n```bash\n# See available engines\n./aixcl engine auto\n\n# Or set manually\n./aixcl engine set ollama   # Recommended for beginners\n./aixcl engine set vllm     # For high-end GPUs\n./aixcl engine set llamacpp  # For GGUF models\n```\n\n**4. Add Your First Model**\n\n```bash\n# Quick test model (smallest, fastest download)\n./aixcl models add qwen2.5-coder:0.5b\n```\n\n\u003e See [Quick Test Models](#quick-test-models) for engine-specific options.\n\n**5. Launch OpenCode**\n\n```bash\n./opencode\n```\n\n\u003e **Note for Open WebUI Users (vLLM/llama.cpp):** When using vLLM or llama.cpp engines, models must be manually configured in Open WebUI:\n\u003e 1. Go to Settings → Connections → Direct Connections\n\u003e 2. Add URL: `http://127.0.0.1:11434/v1` (leave API key empty)\n\u003e 3. Enable \"Direct Connections\" toggle\n\u003e 4. Save and refresh the page\n\u003e\n\u003e The basic configuration is shown above. For additional Open WebUI settings, refer to the Settings page in the Open WebUI interface.\n\n---\n\n## Understanding Model Downloads\n\nModels are downloaded on-demand when you run `./aixcl models add`, not during installation. Download times vary based on model size and your connection speed.\n\n### Download Time Estimates\n\n| Model Size | Approximate File Size | Download Time (100 Mbps) | Download Time (20 Mbps) | Download Time (5 Mbps) |\n|------------|----------------------|--------------------------|-------------------------|------------------------|\n| 0.5B params | ~350-400 MB | ~30 seconds | ~2 minutes | ~5 minutes |\n| 1.5B params | ~1 GB | ~1 minute | ~5 minutes | ~15 minutes |\n| 7B params | ~4-5 GB | ~5 minutes | ~20 minutes | ~45 minutes |\n\n\u003e **Note:** Times are estimates. Actual speeds depend on network conditions and HuggingFace/Ollama server load.\n\n### Engine-Specific Notes\n\n**vLLM Users:** The vLLM container does not include the `hf` CLI. Models must be pre-downloaded on the host before starting vLLM. See the [vLLM Workaround Guide](docs/operations/vllm-model-download-workaround.md) for details.\n\n**llama.cpp Users:** When switching to llama.cpp from another engine, the model configuration in `opencode.json` is cleared. You must re-add a GGUF model for llama.cpp.\n\n---\n\n## Quick Test Models\n\nThese are the smallest viable models for testing your AIXCL setup with OpenCode. **All models below have been tested and verified to work** with the current version of AIXCL.\n\n\u003e **Note:** Using the exact model names shown below ensures compatibility. Other models may work but have not been tested.\n\n### Ollama (Recommended for Beginners)\n\n| Model | Size | Command |\n|-------|------|---------|\n| Qwen2.5-Coder 0.5B | ~398 MB | `./aixcl models add qwen2.5-coder:0.5b` |\n\n\u003e Ollama models use the format `model:tag`. The `0.5b` tag indicates the smallest variant.\n\u003e\n\u003e - [x] Tested: Successfully tested with OpenCode integration ([Test Plan](docs/operations/engine-switching-test-plan.md))\n\n### vLLM\n\n| Model | Size | Command |\n|-------|------|---------|\n| Qwen2.5-Coder 0.5B | ~1 GB* | `./aixcl models add Qwen/Qwen2.5-Coder-0.5B-Instruct` |\n\n\u003e *vLLM downloads the full HuggingFace model (safetensors format), which is larger than GGUF.\n\u003e \n\u003e **Note:** vLLM container does not include `hf` CLI - see workaround guide.\n\u003e \n\u003e - [x] Tested: Successfully tested with OpenCode integration on RTX 4060 ([Test Report](docs/operations/engine-switching-test-report.md))\n\n### llama.cpp\n\n| Model | Size | Command |\n|-------|------|---------|\n| Qwen2.5-Coder 0.5B (Q4_K_M) | ~398 MB | `./aixcl models add Qwen/Qwen2.5-Coder-0.5B-Instruct-GGUF/qwen2.5-coder-0.5b-instruct-q4_k_m.gguf` |\n\n\u003e llama.cpp requires GGUF format models. The format is `username/repo/filename.gguf`.\n\u003e\n\u003e **Note:** When switching engines, the model configuration is cleared. Re-add the GGUF model after switching.\n\u003e\n\u003e - [x] Tested: Successfully tested with OpenCode integration ([Test Plan](docs/operations/engine-switching-test-plan.md))\n\n---\n\n## Management Examples\n\n### 1. Engine Management\n\nAIXCL supports multiple backends. You can switch them instantly:\n\n```bash\n# Auto-detect optimal engine based on your hardware\n./aixcl engine auto\n\n# Manually switch to vLLM (Great for high-end GPUs - see notes below)\n./aixcl engine set vllm\n\n# Manually switch to llama.cpp (Great for CPU/Apple Silicon)\n./aixcl engine set llamacpp\n\n# Restart to apply changes\n./aixcl stack restart engine\n```\n\n\u003e **vLLM GPU Compatibility:** vLLM requires specific GPU tuning for different cards. If you encounter CUDA errors on startup, the default configuration includes optimizations for RTX 4060 and similar GPUs. For other GPUs, you may need to adjust `--gpu-memory-utilization` and `--max-model-len` in `services/docker-compose.yml`.\n\n\u003e **Engine Testing:** All engines have been tested and validated. See the [Engine Switching Test Plan](docs/operations/engine-switching-test-plan.md) for comprehensive testing details.\n\n### 2. Model Management\n\nManage your local library across any active engine:\n\n**Ollama Engine:**\n```bash\n# Add from Ollama Registry (tested model)\n./aixcl models add qwen2.5-coder:0.5b\n\n# Add multiple models\n./aixcl models add qwen2.5-coder:0.5b qwen2.5-coder:1.5b\n\n# List all local models\n./aixcl models list\n\n# Remove a model\n./aixcl models remove qwen2.5-coder:0.5b\n```\n\n**vLLM Engine:**\n```bash\n# Add from HuggingFace (full model path) - tested model\n./aixcl models add Qwen/Qwen2.5-Coder-0.5B-Instruct\n\n# List downloaded models\n./aixcl models list\n```\n\n**llama.cpp Engine:**\n```bash\n# Add GGUF from HuggingFace (requires full path with filename) - tested model\n./aixcl models add Qwen/Qwen2.5-Coder-0.5B-Instruct-GGUF/qwen2.5-coder-0.5b-instruct-q4_k_m.gguf\n\n# List GGUF files in volume\n./aixcl models list\n```\n\n### 3. OpenCode CLI Integration\n\nAIXCL is designed to power local agentic development workflows via the OpenCode CLI. OpenCode connects to your stack for local chat, autocomplete, and agentic coding - all running on-device.\n\n* **Endpoint:** `http://localhost:11434/v1`\n* **Start a session:** `./opencode`\n* **Setup:** See [OpenCode Setup Guide](https://github.com/xencon/aixcl/blob/main/docs/developer/opencode-setup.md) for full configuration details.\n\nAgent workflow rules and permissions are configured automatically via `opencode.json` and `DEVELOPMENT.md`.\n\n---\n\n## Common Commands\n\n| Command | Description |\n| --- | --- |\n| `./aixcl utils check-env` | Validate environment and dependencies |\n| `./aixcl stack start --profile sys` | Start all services with sys profile |\n| `./aixcl stack status` | Check service health and OpenCode connectivity |\n| `./aixcl stack logs engine` | View real-time inference logs |\n| `./aixcl stack stop` | Stop all services gracefully |\n| `./aixcl restart` | Restart services (shorthand for stack restart) |\n| `./aixcl service restart engine` | Restart a specific service |\n| `./aixcl models add \u003cmodel\u003e` | Add a model (e.g., `qwen2.5-coder:0.5b`) |\n| `./aixcl models remove \u003cmodel\u003e` | Remove a model |\n| `./aixcl models list` | List installed models |\n| `./aixcl utils clean` | Wipe unused containers and volumes (Fresh start) |\n\n---\n\n## Documentation\n\n* [User Guide](https://github.com/xencon/aixcl/blob/main/docs/user/usage.md) - Detailed workflows and tips.\n* [Architecture](https://github.com/xencon/aixcl/blob/main/docs/architecture/governance) - Profiles and service contracts.\n* [Security](https://github.com/xencon/aixcl/blob/main/docs/operations/security.md) - Rootless Docker operations (Podman support: experimental).\n* [OpenCode Setup](https://github.com/xencon/aixcl/blob/main/docs/developer/opencode-setup.md) - CLI configuration and agent workflow.\n* [Contributing](https://github.com/xencon/aixcl/blob/main/DEVELOPMENT.md) - Issue-first workflow, templates, and PR requirements.\n\n## License\n\nApache License 2.0 - See [LICENSE](https://github.com/xencon/aixcl/blob/main/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxencon%2Faixcl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxencon%2Faixcl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxencon%2Faixcl/lists"}