116 lines
4.9 KiB
Markdown
116 lines
4.9 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` pointed at the loopback proxy;
|
|
the entire credential-bearing env family (`ANTHROPIC_*`, `AWS_*`, `GOOGLE_CLOUD_*`,
|
|
`GOOGLE_APPLICATION_CREDENTIALS`, `*_TOKEN`, `*_KEY`, `*_SECRET`, …) is stripped
|
|
from the composed environment. The Bedrock/Vertex routing switches
|
|
(`CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, and the `_SKIP_*_AUTH`
|
|
pair) are force-removed regardless of value — otherwise their mere presence
|
|
would route Claude Code to the real Anthropic API via AWS/GCP and bypass the
|
|
proxy. 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.
|