claude-local-stack

Requires Apple Silicon (M1/M2/M3/M4) — MLX inference is ARM-only. macOS only.

Local AI stack for Claude Code on Apple Silicon. Configuration per profile:

• offline mono or multi-model routing,
• cloud With token optimization

Since I work with many llm model and tool, it was time for me to try to manage all the mess in a more rational way. This stack is far from state of the art, but it help me a lot for :

• my daily job
• encrypt secret (and don't wrote them everywhere ...)
• manage token compression, plugins configuration
• start playing with voice (STT/TTS) integration
• experimenting model

I know that my installation and scripts are macos only... But with the help of an agent and local docs, i'm sure that you could translate all this stack for your personal computer.

Architecture

Default Profile (fully local)

flowchart LR
    CC[Claude Code] --> H[Headroom :8787]
    H --> B[Bifrost :4000]
    B --> R[rapid-mlx :8000]
    R --> M[Qwen3.6-35B-A3B MLX]

Max Profile (Anthropic API via Claude Max plan)

flowchart LR
    CC[Claude Code] --> H[Headroom :8787]
    H --> B[Bifrost :4000]
    B --> A[Anthropic API]
    A --> Claude[Claude Sonnet/Opus]

Cloud Profile (AWS Bedrock)

flowchart LR
    CC[Claude Code] --> H[Headroom :8787]
    H --> B[Bifrost :4000]
    B --> BK[AWS Bedrock]
    BK --> Claude[Claude Sonnet/Opus]

Components

Claude Plugins

Stack Technologies

Stack Runtimes

Quick start

1. Clone: cd $HOME && git clone <repo> claude-local-stack
2. Configure your shell — add AI_HOME, PATH, aliases to ~/.zshrc/~/.zshenv
3. Bootstrap: ai-install (prerequisites, runtimes, tooling)
4. Set secrets: ai-secrets init then ai-secrets edit — add ANTHROPIC_API_KEY, HF_TOKEN, etc.
5. Activate a profile: ai-stack profile local
6. Install profile deps: ai-stack install
7. Start the stack: ai-stack start
8. Launch Claude: aclaude, or VS Code: acode

If anything goes wrong: see docs/troubleshooting.md.

Profiles

Switch routing strategy, models, and services per workflow:

• local: local only — no cloud account needed
• bedrock: AWS Bedrock — requires AWS CLI configured with Bedrock access
• max: Anthropic API — requires Anthropic API key

ai-stack profile local   # switch profile
ai-stack profile          # show current

See docs/profiles.md for routing matrix and details.

CLI reference

See docs/cli.md for full reference.

Stack management

ai-stack start              # start all services
ai-stack stop               # stop all
ai-stack restart [svc]      # restart all or one
ai-stack status             # running processes
ai-stack logs [svc]         # stream or attach logs
ai-stack enable <svc...>    # uncomment service, restart if running
ai-stack disable <svc...>   # comment service, restart if running
ai-stack shell              # subshell with env + secrets loaded
ai-stack check [profile]    # dep report for active (or named) profile
ai-stack install [profile]  # install all missing deps

Installation

ai-install                  # bootstrap (prerequisites, runtimes, tooling)
ai-stack install            # install services + plugins for active profile
ai-stack install <profile>  # install for a named profile without switching

Secrets

ai-secrets init             # generate age key + SOPS config
ai-secrets edit             # decrypt → edit → re-encrypt
ai-secrets get <key>        # print one value
ai-secrets show             # show all
ai-secrets rotate           # rotate keys

Models

Even if this client sit on top of hf (hugging face), I still like to see somewhere a list of my model than I use ... This cli use hugging face local cache to store them, as most of our tool use it, it fix my fears....

ai-models pull              # download all
ai-models pull llm          # download a category
ai-models list              # show manifest + status

See docs/cli.md for full reference.

Integration

Point any tool at http://localhost:8787 with ANTHROPIC_API_KEY=local.

ANTHROPIC_API_KEY=local is a sentinel value — Headroom intercepts requests at port 8787 and routes them to the active profile backend. No real Anthropic key is sent when using local/Bedrock profiles.

Repository layout

ai-stack/
├── bin/              # CLI tools (ai-stack, ai-install, ai-secrets, ai-models)
├── config/
│   ├── ai-stack.env        # project paths
│   ├── base-services.yaml  # universal deps (claude-code, superpowers, overmind)
│   ├── profiles/           # profile definitions (local, bedrock, bedrock-direct, max, mistral, …)
│   ├── Procfile            # active service definitions
│   └── models.yaml         # model manifest
├── lib/
│   ├── setup/        # one-shot bootstrap scripts (prerequisites, runtimes, tooling)
│   ├── services/     # daemons: rapid-mlx, bifrost, headroom, ollama, voicemode; tools: llm-wiki
│   ├── plugins/      # Claude Code plugins (rtk, context-mode, superpowers, caveman, agent-skills…)
│   └── utils/        # helpers (supervised-launch, load-service-env, token-savings)
├── secrets/          # SOPS-encrypted keys
├── logs/             # runtime logs (gitignored)
└── docs/

What's gitignored

• secrets/age-key.txt — private key
• secrets/api-keys.sops.yaml — encrypted secrets
• config/.active-profile — runtime state
• logs/ — runtime output
• lib/services/*/.venv/ — recreated via install

Docs