ab8c9a2d4b
All checks were successful
ci/woodpecker/pr/ci Pipeline was successful
Second and final PR for `mosaic [yolo] claudex` — runs GPT models inside the Claude Code harness via claude-code-proxy (ChatGPT-subscription OAuth). Builds on the PR-1 preflight/lifecycle library (#793). New `claudex.ts` (pure / dependency-injected composition): - resolveClaudexConfigDir / assertIsolatedConfigDir — the isolated CLAUDE_CONFIG_DIR seam. HARD REQ 1 (provable isolation): canonicalizes both sides, rejects `~/.claude` and any descendant, ensures the dir 0700, then re-checks post-create and rejects a symlinked target (TOCTOU). Ambient CLAUDE_CONFIG_DIR is never inherited. Fails closed on any uncertainty. - buildClaudexEnv — HARD REQ 2 (zero token leakage): strips the entire credential-bearing env family (ANTHROPIC_*, *_TOKEN, *_API_KEY, *_SECRET, CLAUDE_CODE_OAUTH*) and hands Claude Code only ANTHROPIC_AUTH_TOKEN=unused. Never reads the proxy credential file. Returns a fresh object (no mutation). - resolveClaudexModels — P3 tier map: primary→gpt-5.6-sol, small/fast→gpt-5.6-luna; operator env values win. - buildClaudexBanner / buildClaudexContractNote — P4 EXPERIMENTAL classification (no token material by construction). - runClaudexProxyGate — preflight → device reauth (only when needed) → ensure a trusted-live listener → re-preflight; surfaces non-sensitive problems only. - launchClaudex — fail-closed DI orchestration: preflight → gate → compose env → exec; never reaches exec on a gate failure or guard throw. Proxy endpoint imported from claudex-proxy.ts (single source of truth). launch.ts wiring: - execRuntime gains an env parameter. - `claudex` + `yolo claudex` commander dispatch (keeps the #454 arg-slice fix); claudexHandler is an injectable seam for the wiring tests. - launchClaudexProduction glue assembles the real harness adapter. Tests: 45 claudex specs + 5 launch wiring specs, TDD red-first. New-module coverage 99% stmts/lines, 93% branch (≥85% gate). Full mosaic suite 1164 green; typecheck / lint / format:check green. Refs #790 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
111 lines
4.6 KiB
Markdown
111 lines
4.6 KiB
Markdown
# @mosaicstack/mosaic
|
|
|
|
CLI package for the Mosaic self-hosted AI agent platform.
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
mosaic wizard # First-run setup wizard
|
|
mosaic gateway install # Install the gateway daemon
|
|
mosaic config show # View current configuration
|
|
mosaic config hooks list # Manage Claude hooks
|
|
```
|
|
|
|
## Headless / CI Installation
|
|
|
|
Set `MOSAIC_ASSUME_YES=1` (or ensure stdin is not a TTY) to skip all interactive prompts. The following environment variables control the install:
|
|
|
|
### Gateway configuration (`mosaic gateway install`)
|
|
|
|
| Variable | Default | Required |
|
|
| -------------------------- | ----------------------- | ------------------ |
|
|
| `MOSAIC_STORAGE_TIER` | `local` | No |
|
|
| `MOSAIC_GATEWAY_PORT` | `14242` | No |
|
|
| `MOSAIC_DATABASE_URL` | _(none)_ | Yes if tier=`team` |
|
|
| `MOSAIC_VALKEY_URL` | _(none)_ | Yes if tier=`team` |
|
|
| `MOSAIC_ANTHROPIC_API_KEY` | _(none)_ | No |
|
|
| `MOSAIC_CORS_ORIGIN` | `http://localhost:3000` | No |
|
|
|
|
### Admin user bootstrap
|
|
|
|
| Variable | Default | Required |
|
|
| ----------------------- | -------- | -------------- |
|
|
| `MOSAIC_ADMIN_NAME` | _(none)_ | Yes (headless) |
|
|
| `MOSAIC_ADMIN_EMAIL` | _(none)_ | Yes (headless) |
|
|
| `MOSAIC_ADMIN_PASSWORD` | _(none)_ | Yes (headless) |
|
|
|
|
`MOSAIC_ADMIN_PASSWORD` must be at least 8 characters. In headless mode a missing or too-short password causes a non-zero exit.
|
|
|
|
### Example: Docker / CI install
|
|
|
|
```bash
|
|
export MOSAIC_ASSUME_YES=1
|
|
export MOSAIC_ADMIN_NAME="Admin"
|
|
export MOSAIC_ADMIN_EMAIL="admin@example.com"
|
|
export MOSAIC_ADMIN_PASSWORD="securepass123"
|
|
|
|
mosaic gateway install
|
|
```
|
|
|
|
## Runtime launchers
|
|
|
|
```bash
|
|
mosaic claude # Launch Claude Code with Mosaic injection
|
|
mosaic yolo claude # …with --dangerously-skip-permissions
|
|
mosaic codex | opencode | pi
|
|
```
|
|
|
|
### `mosaic claudex` (EXPERIMENTAL)
|
|
|
|
Runs GPT models **inside the Claude Code harness** by pointing Claude Code at a
|
|
local [`claude-code-proxy`](https://github.com/raine/claude-code-proxy) that
|
|
translates the Anthropic Messages API to a ChatGPT-subscription (Codex OAuth)
|
|
backend. This is **not Anthropic Claude** — model behavior, tool use, and output
|
|
quality may differ. Intended for evaluation, not production delivery.
|
|
|
|
```bash
|
|
mosaic claudex # launch (prompts through the proxy readiness gate)
|
|
mosaic yolo claudex # …with --dangerously-skip-permissions
|
|
mosaic claudex --print "hello" # trailing args are forwarded to Claude Code
|
|
```
|
|
|
|
**Prerequisite:** the `claude-code-proxy` binary must be installed and
|
|
authenticated (`claude-code-proxy codex auth …`). `mosaic claudex` runs a
|
|
preflight that verifies the binary, the OAuth state (triggering a device re-auth
|
|
if needed), and a trusted local listener before launching; it **fails closed**
|
|
if the proxy cannot be brought up with a verified identity.
|
|
|
|
**Isolation (never touches your real Claude state).** claudex always launches
|
|
against an isolated `CLAUDE_CONFIG_DIR` (default `~/.config/mosaic/claudex/home`).
|
|
The ambient `CLAUDE_CONFIG_DIR` is deliberately ignored, and a guard proves the
|
|
resolved dir can never be — or live under — the real `~/.claude`. A claudex
|
|
session therefore cannot mutate your normal Claude Code config.
|
|
|
|
**No token leakage.** claudex never reads the proxy's credential file. Claude
|
|
Code is handed only `ANTHROPIC_AUTH_TOKEN=unused`; the entire credential-bearing
|
|
env family (`ANTHROPIC_*`, `*_TOKEN`, `*_API_KEY`, `*_SECRET`, …) is stripped
|
|
from the composed environment. The proxy holds the real OAuth credential.
|
|
|
|
**Model tiers (override via env).**
|
|
|
|
| Tier | Env var | Default |
|
|
| --------------------- | ---------------------------- | -------------- |
|
|
| primary (opus/sonnet) | `ANTHROPIC_MODEL` | `gpt-5.6-sol` |
|
|
| small/fast (haiku) | `ANTHROPIC_SMALL_FAST_MODEL` | `gpt-5.6-luna` |
|
|
|
|
Operator-provided values win over the defaults. Additional overrides:
|
|
`MOSAIC_CLAUDEX_CONFIG_DIR` (isolated config dir), `ANTHROPIC_BASE_URL` (proxy
|
|
endpoint).
|
|
|
|
## Hooks management
|
|
|
|
After running `mosaic wizard`, Claude hooks are installed in `~/.claude/hooks-config.json`.
|
|
|
|
```bash
|
|
mosaic config hooks list # Show all hooks and enabled/disabled status
|
|
mosaic config hooks disable PostToolUse # Disable a hook (reversible)
|
|
mosaic config hooks enable PostToolUse # Re-enable a disabled hook
|
|
```
|
|
|
|
Set `CLAUDE_HOME` to override the default `~/.claude` directory.
|