haylanandClaude-Bot
c01ef8965d
Resolves wayfinder ticket #8. The stack is reached over LAN/WAN hostnames, not localhost: - Open WebUI: ai.home (LAN) and ai.haylan.ch (external, via DMZ) routed through the existing Nginx Proxy Manager instance to the published WEBUI_PORT — no new reverse-proxy service needed in this repo. - llama.cpp's raw API stays LAN-only and unregistered in NPM (no auth of its own); coding CLIs reach it via the box's LAN IP or ai.home directly. New docs/network-access.md documents the NPM proxy-host setup and the LAN-only decision. coding-cli-setup.md and README updated to stop referencing localhost. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
90 lines
4.5 KiB
Markdown
90 lines
4.5 KiB
Markdown
# Pointing a coding-agent CLI at this stack
|
|
|
|
This stack's llama.cpp server exposes two endpoints once `docker compose up` is running (see `docker-compose.yml`):
|
|
|
|
- **OpenAI-compatible**: `http://<ai-box>:8080/v1` (or `${LLAMA_PORT}` if you changed it in `.env`)
|
|
- **Anthropic Messages API shim**: `http://<ai-box>:8080` (adds `/v1/messages`)
|
|
|
|
Both serve the same model — `Qwen3.8-27B-UD-Q4_K_XL.gguf` — behind whichever wire format the client speaks.
|
|
|
|
`<ai-box>` is this machine's LAN address — its LAN IP, or `ai.home` if your local DNS resolves that hostname directly to the box. **This API is LAN-only, not reachable via `ai.haylan.ch`** — it's deliberately not registered in Nginx Proxy Manager (no auth of its own, unlike Open WebUI). See `docs/network-access.md`. If you're running a coding CLI from this machine itself, `localhost` works too.
|
|
|
|
> **Read this before relying on it for real work.** Qwen3.8-27B's tool-calling has **documented, open llama.cpp upstream bugs** (parser fails on text before `<tool_call>`, tool calls emitted as inert XML inside thinking blocks — see `docs/research/qwen3.8-27b-tool-calling.md`). Every setup below inherits this risk identically, regardless of which CLI or wire format you use. Don't trust it for unattended multi-step agentic work until you've run the smoke test in [issue #5](https://git.arthurerlich.de/haylan/LLM-Server/issues/5).
|
|
|
|
## Claude Code CLI
|
|
|
|
Claude Code speaks the **Anthropic Messages API** — point it at the shim, not the OpenAI-compatible endpoint:
|
|
|
|
```bash
|
|
export ANTHROPIC_BASE_URL=http://<ai-box>:8080
|
|
export ANTHROPIC_API_KEY=local # value is unchecked by llama.cpp, but the client requires it set
|
|
claude
|
|
```
|
|
|
|
Requires llama.cpp's `--jinja` flag (already set in `docker-compose.yml`) — without it, tool-use requests fail outright.
|
|
|
|
## Kimi CLI
|
|
|
|
Kimi CLI speaks plain **OpenAI Chat Completions** — no shim needed. Configure a provider block in its config file (`config.toml`):
|
|
|
|
```toml
|
|
[providers.openai]
|
|
type = "openai"
|
|
base_url = "http://<ai-box>:8080/v1"
|
|
api_key = "local"
|
|
```
|
|
|
|
If Kimi CLI's response parsing gets confused by Qwen's `<think>...</think>` reasoning tags, check its `reasoning_key` setting — it's configurable for non-standard local server responses.
|
|
|
|
## OpenCode CLI
|
|
|
|
Confirmed project: **`anomalyco/opencode`** (renamed from `sst/opencode` — don't confuse with the unrelated `opencode-ai/opencode` Go TUI). Docs: https://opencode.ai/docs/
|
|
|
|
**Install**:
|
|
```bash
|
|
curl -fsSL https://opencode.ai/install | bash
|
|
```
|
|
|
|
**Config** (`opencode.json`, project root or `~/.config/opencode/opencode.json`):
|
|
|
|
```json
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"provider": {
|
|
"llamacpp": {
|
|
"npm": "@ai-sdk/openai-compatible",
|
|
"name": "llama.cpp (local)",
|
|
"options": {
|
|
"baseURL": "http://<ai-box>:8080/v1",
|
|
"apiKey": "sk-local-not-checked"
|
|
},
|
|
"models": {
|
|
"qwen3.8-27b": {
|
|
"name": "Qwen3.8-27B",
|
|
"limit": { "context": 65536, "output": 8192 }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Set `limit.context` to match whatever `LLAMA_CTX_SIZE` this stack is actually running with (`.env`), not a value assumed from the model card — OpenCode uses it for its own context-management bookkeeping, not the server.
|
|
|
|
Select the model with `llamacpp/qwen3.8-27b`.
|
|
|
|
**OpenCode-specific risks** (on top of the shared Qwen3.8-27B tool-calling risk above):
|
|
- Requires llama.cpp's `--jinja` flag (already set) — without it, OpenCode's unconditional tool-call scaffolding gets a 500.
|
|
- [anomalyco/opencode#20669](https://github.com/anomalyco/opencode/issues/20669) (closed as "not planned" — a live, unfixed risk): OpenCode's `bash` tool crashes if the model omits the optional `description` field on a tool call; some local backends return `finish_reason: tool_calls` with an empty array, which can hang the agent loop instead of stopping cleanly.
|
|
- Thinking-mode handling (`options.reasoningEffort`) is undocumented for models that emit inline `<think>` tags rather than a native reasoning API field — expect no effect from that config on this model; untested.
|
|
|
|
## Summary
|
|
|
|
| CLI | Wire format | Endpoint | Config |
|
|
|---|---|---|---|
|
|
| Claude Code | Anthropic Messages | `http://<ai-box>:8080` | `ANTHROPIC_BASE_URL` env var |
|
|
| Kimi CLI | OpenAI Chat Completions | `http://<ai-box>:8080/v1` | `config.toml` provider block |
|
|
| OpenCode | OpenAI Chat Completions | `http://<ai-box>:8080/v1` | `opencode.json` provider block |
|
|
|
|
Further reading: `docs/research/qwen3.8-27b-tool-calling.md`, `docs/research/opencode-cli-setup.md`.
|