OpenCode Initializer v3.2.0

Operating Model: Multi-Agent Framework v3.0

Wave: current_wave.md

Checkpoint: session_checkpoint.json

AI-Native SDD Harness — one-command AI-enhanced development environment for WSL2, Linux, and macOS. 4 deployment profiles.
_{685-line orchestrator · 52 modules · 12 modes · 24 MCPs · 15 plugins · 13 LSPs · 23 providers · air-gap · governance · PII guard · audit trail · offline bundle}

Quick Start

curl -fsSL https://raw.githubusercontent.com/AlexanderNarbaev/opencode_initializer/main/setup.sh | bash -s -- --full

One command installs everything: 8 languages, 52 infrastructure modules, 24 MCP servers, 15 OpenCode plugins, 13 LSP servers, 23 AI providers, infrastructure as code (PostgreSQL + Qdrant + Redis + Prometheus + Grafana + Node Exporter + MemoryLayer), Cockpit TUI (7 tabs), Web GUI, Isolated Circuit Mode, hardware auto-detection, Lynis CIS scanner, auditd kernel rules, and SearXNG web search.

Full Documentation

macOS users: Requires bash>=4 and grep with -E support (GNU grep). Install via brew install bash grep. Associative arrays (declare -A) require bash>=4; macOS stock bash 3.2 needs brew install bash.

Feature Grid

v2.0.0 — Infrastructure as Code + Isolated Circuit + Observability

• Infrastructure as Code: PostgreSQL + Qdrant + Redis + Prometheus + Grafana + Node Exporter + MemoryLayer via Docker Compose
• Cockpit TUI: 7-tab terminal UI (Services, Plugins, GPU/Models, Sessions, Tasks, Logs, Infra)
• Web GUI: Full management dashboard on port 4200 with Metrics iframe, model switching, infrastructure control
• Isolated Circuit Mode: Air-gapped LLM operation with local OpenAI-compatible backends (Ollama, vLLM, SGLang)
• z.ai GLM-5.2: Primary provider for RU/CN markets, OpenAI-compatible API, free tier
• OpenRouter: Aggregator access to 100+ models via single API key
• OpenCode Metrics: Real-time Prometheus exporter on port 9464 — sessions, WAL entries, container health, Ollama models, active configuration
• Node Exporter: System-level metrics (CPU, RAM, disk, uptime) scraped by Prometheus
• Grafana Dashboards: Infrastructure overview + Agent performance — auto-provisioned
• Port Auto-Detection: Automatic port conflict resolution with shifting — env var overrides for all services
• Deployment Profiles: personal / corporate / airgapped / hybrid with per-service mode control (local/external/disabled)
• Unified Service Layer: Single configuration point for all 18 infrastructure services via setup.conf
• External Service Support: Point any component to external URLs — corporate OTel, existing Grafana, managed databases
• MemoryLayer: AI memory system with Ollama embed proxy (mxbai-embed-large, 1024-dim)

v3.0.0 — SDD-native AI Harness: Audit & Governance

• Model Governance (43-governance.sh): model-policy.json per-project allowlist/blocklist, 3 enforcement modes (allow-all/allowlist/corporate)
• PII Sanitizer (45-pii-guard.sh): 9 detectors (email, phone, INN, SNILS, passport, credit card, IP, API key) — pre-LLM-request gate
• Audit Trail (44-audit.sh): 7 WAL event types (model_call, tool_call, provider_switch, pii_redacted, checkpoint, error, session_boundary), SHA-256 hash-chain, rotation >10MB → gzip+Qdrant
• Constitution + Spec Format (41-constitution.sh): memory/constitution.md generator, SDD workflow (constitution→specify→clarify→plan→tasks→implement→verify→converge)
• Lifecycle Hooks (42-hooks.sh): pre-request, post-response, pre-commit, on-error hooks framework
• Offline Bundle (46-offline-bundle.sh): dev bundle create for fully air-gapped installation, SHA-256 manifest
• Supply-Chain Hardening: curl|sh → download+verify SHA256 for all 6 affected modules (mise, devbox, WasmEdge, Shokunin, Oh My Zsh)
• SOC2/ISO27001 Ready: Compliance checklists (CC5.2/CC7.2/CC8.2, A.9/A.12/A.14/A.16/A.17/A.18 + GDPR Art.32/35)
• Scheduled Security: Systemd timer for daily Trivy + Qodana scan, SBOM generation (CycloneDX), pre-commit hook

Architecture

opencode_initializer/
├── setup.sh                  # Orchestrator (685 lines)
├── dev.sh                    # CLI: dev install|remove|update|health|metrics|observability|isolated|...
├── opencode.json             # Generated OpenCode multi-provider config (23 providers)
├── src/
│   ├── lib/                  # 42 modules (39 numbered + 3 helpers)
│   │   ├── helpers.sh        # _curl, _retry, _npm_install infrastructure
│   │   ├── 00-core.sh        # OS/PKG/ARCH detection, mirrors, progress, ISOLATED_CIRCUIT, port resolution
│   │   ├── 01-system.sh      # System packages (cross-distro: apt/dnf/pacman/apk/zypper/brew)
│   │   ├── ...               # 02-29: Languages, tools, infrastructure
│   │   ├── 30-infra.sh       # Infrastructure: PostgreSQL + Qdrant + Redis + Prometheus + Grafana + Node Exporter + MemoryLayer
│   │   ├── 31-cockpit.sh     # Cockpit TUI server management daemon (7-tab)
│   │   ├── 32-isolated.sh    # Isolated Circuit Mode — air-gapped LLM
│   │   ├── 33-services.sh    # Unified Service Layer — port resolution, service modes, deployment profiles
│   │   ├── 34-observability.sh  # Prometheus + Grafana observability stack + OTel
│   │   ├── 35-gui.sh         # Web GUI (Node.js, port 4200)
│   │   ├── 36-model-router.sh   # Model routing intelligence (8 task profiles, cost table)
│   │   ├── 37-wal.sh         # Write-Ahead Log — setup + agent session journal
│   │   ├── version-check.sh  # Version comparison (8+ tools)
│   │   └── pre-session-check.sh  # Pre-session provider/model validation
│   ├── cockpit/               # Go TUI source (BubbleTea framework)
│   ├── gui/                   # Web GUI (Node.js server + HTML dashboard)
│   ├── grafana/               # Grafana provisioning (datasources + dashboards)
│   ├── systemd/               # Systemd user units (opencode-metrics.service)
│   └── modes/                 # 5 mode scripts (+ 6 built-in)
├── scripts/                   # Utilities (provider-check, embed-proxy, ai-router, oc-*)
│   ├── oc-metrics.py          # OpenCode Prometheus metrics exporter (:9464)
│   ├── oc-sdk.py              # Python SDK
│   ├── embed-proxy.py         # Ollama → MemoryLayer embedding bridge
│   └── ai-router/             # Model routing intelligence
├── tests/                     # Unit (12), integration (5), E2E (4) — 398+ assertions
├── migrations/                # Timestamped, idempotent migrations
├── docs/                      # MkDocs Material documentation site (EN/RU)
├── .github/                   # CI workflows (test, shellcheck, build, security, docs)
└── CHANGELOG.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, LICENSE

Modes

Installation

Full Install

curl -fsSL https://raw.githubusercontent.com/AlexanderNarbaev/opencode_initializer/main/setup.sh | bash -s -- --full

With API Keys

bash setup.sh --full \
  --deepseek-key "sk-..." \
  --zai-key "..." \
  --openrouter-key "sk-or-..." \
  --xai-key "xai-..." \
  --github-token "ghp_..." \
  --gitlab-token "glpat-..."

Deployment Profiles

# Corporate environment — point to existing infrastructure
DEPLOYMENT_PROFILE=corporate \
  POSTGRES_MODE=external POSTGRES_EXTERNAL_URL=pg.internal:5432 \
  GRAFANA_MODE=external EXTERNAL_GRAFANA_URL=https://grafana.company.com \
  PROMETHEUS_MODE=external EXTERNAL_PROMETHEUS_URL=https://prom.internal:9090 \
  OTEL_EXPORTER_ENABLED=true OTEL_EXPORTER_ENDPOINT=otel-collector:4317 \
  bash setup.sh --full

# Air-gapped — local LLMs only
bash setup.sh --full --isolated

Interactive

bash setup.sh --interactive     # Choose what to install
bash setup.sh --dry-run --full  # Preview without changes

Post-Install CLI

dev health              # Full diagnostics (65+ checks)
dev list                # List installed components
dev update              # Update everything + migrations
dev self-update         # Update the installer itself
dev version-check       # Compare installed vs latest versions
dev config              # Edit setup config file
dev provider-check      # Check AI provider connectivity
dev autoupdate          # Run topgrade full system update
dev remove java         # Remove a component
dev plugins list        # Show installed plugins

# Observability
dev observability status    # Prometheus + Grafana status
dev observability reload    # Regenerate prometheus.yml + restart
dev metrics start           # Start metrics exporter
dev metrics status          # View real-time metrics

# Infrastructure
dev infra up                # Start all Docker services
dev infra status            # Container health overview
dev infra down              # Stop all services

# Isolated Circuit (air-gapped LLM)
dev isolated on              # Enable local-only mode
dev isolated status          # Check current state

# Model Management
dev models coding            # Get model recommendation for coding
dev models install qwen3:32b # Download local model
dev models list-local        # List installed local models

# GUI & Cockpit
dev gui start                # Start Web GUI (http://localhost:4200)
cockpit                      # Launch TUI (or run 'dev install cockpit')

# Backup
dev backup create            # Backup all configs
dev backup list              # Show available backups
dev backup restore <file>    # Restore from backup

# Add components later
dev install llm              # Add GPU/LLM support
dev install docker           # Install Docker Engine

Observability Stack

Components

Dashboards

• Infrastructure Overview (/d/opencode-infra): Container status, PostgreSQL connections, Redis memory, Qdrant collections, service uptime
• Agent Performance (/d/opencode-tokens): Token usage, cost estimates, active sessions, model distribution, provider costs

Access

# Web GUI Metrics tab
http://localhost:4200  →  Metrics tab (Grafana iframe)

# Cockpit TUI
cockpit → Tab 8 (Grafana) → Press 'o' to open in browser

# Direct
http://localhost:3001  →  Grafana (admin/admin)
http://localhost:9090  →  Prometheus
http://localhost:9464/metrics  →  OpenCode metrics

Port Management

All service ports are configurable via environment variables or ~/.config/opencode-setup/setup.conf:

# Override default ports
POSTGRES_PORT=5433
GRAFANA_PORT=3002
METRICS_EXPORTER_PORT=9465

# Or use auto-detection (set to 0)
POSTGRES_PORT=0   # Finds first free port ≥ 5432

# Service modes
POSTGRES_MODE=external  POSTGRES_EXTERNAL_URL=pg.internal:5432
REDIS_MODE=disabled

Options

Resilience

• Progress tracking: ~/.cache/opencode-setup/progress records completed steps — re-runs are idempotent
• Retry logic: All curl downloads use 5 retries with exponential backoff
• Mirror fallback: Auto-detects inaccessible services and switches to mirrors (ghproxy.com, npmmirror.com, yandex.ru, goproxy.cn)
• npm pack cache: MCP .tgz files cached locally, survive npm cache clears
• Bun binary paths: Absolute paths to ~/.bun/bin/ — 0.5s cold start vs 5-15s with npx
• Port auto-detection: Collision-safe port assignment with automatic shifting
• WSL2 optimization: DNS fix, memory limits, mirrored networking, .wslconfig tuning
• Dry-run mode: Preview all changes without executing them
• Isolated Circuit: Air-gapped LLM operation with auto-detection of local backends
• Deployment profiles: Pre-configured behaviors for personal, corporate, airgapped, and hybrid environments

Platform Support

Security

• All secrets in ~/.config/opencode/secrets.env (chmod 600)
• opencode-dcp + opencode-vibeguard: context pruning, PII/secret filtering
• No hardcoded credentials in any source file
• All API keys via CLI arguments only
• ShellCheck CI on every push and PR
• Metrics exporter binds to 127.0.0.1 (local only)
• Systemd services run as user (no root)
• MIT licensed

Documentation

• Full Guide — MkDocs Material site (EN/RU)
• Team Setup Guide — onboarding colleagues
• Architecture — C4 diagrams, module reference
• AGENTS.md — AI agent documentation
• Contributing Guide
• Security Policy
• Code of Conduct
• Changelog

Community

• GitHub Issues
• GitVerse Mirror

License

MIT (c) 2025-2026 Alexander Narbaev