Getting Started¶

New to opencode_initializer? This guide walks you through everything — from zero to a fully working AI-enhanced development environment.

What You Need¶

System Requirements¶

Before You Start¶

1. Fresh OS install recommended (or at least a clean user)
2. Internet connection — the script downloads lots of packages
3. Sudo access — you'll need to enter your password
4. Review the script — curl -fsSL <url> | less before piping to bash

Installation¶

Option 1: One-liner (easiest)¶

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

Option 2: Clone and run (more control)¶

git clone https://github.com/AlexanderNarbaev/opencode_initializer.git ~/opencode_initializer
cd ~/opencode_initializer
bash setup.sh

Option 3: Specific mode¶

# Health check only (no changes)
bash setup.sh --health

# Interactive — choose what to install
bash setup.sh --interactive

# New project only (skip system tools)
bash setup.sh --new ~/my-project

# Preview mode (dry-run)
bash setup.sh --dry-run

# Refresh tools, keep data
bash setup.sh --reinit

# CI/CD headless mode (no GUI, no Docker, no ZSH)
bash setup.sh --ci

API Keys¶

Provide API keys to enable full AI functionality. All keys are optional — the script works without them, but MCP servers and providers that require keys will be disabled.

Quick Start with Keys¶

bash setup.sh --full \
  --deepseek-key "sk-..." \
  --github-token "ghp_..." \
  --gitlab-token "glpat-..." \
  --google-maps-key "..."

All Available Key Options¶

Flag	Service	Required For	Free Tier
-k, --api-key	OpenCode Go	OpenCode provider	—
--deepseek-key	DeepSeek	DeepSeek provider	platform.deepseek.com
--xai-key	xAI Grok	xAI/Grok provider	—
--mimo-key	Xiaomi MiMo	MiMo provider	—
--minimax-key	MiniMax M3	MiniMax provider	—
--github-token	GitHub (classic token)	GitHub MCP server, gh CLI	Free, no scopes needed
--gitlab-token	GitLab	GitLab MCP server	read_api scope
--google-maps-key	Google Maps	Google Maps MCP server	Free tier available

Additional Environment Variables¶

For providers not available as CLI flags, set environment variables before running:

export OPENAI_API_KEY="sk-..."        # OpenAI
export ANTHROPIC_API_KEY="sk-..."     # Anthropic Claude
export GOOGLE_API_KEY="..."           # Google Gemini
export GROQ_API_KEY="gsk_..."         # Groq
export TOGETHER_API_KEY="..."         # Together AI
export FIREWORKS_API_KEY="..."        # Fireworks
export MISTRAL_API_KEY="..."          # Mistral
export COHERE_API_KEY="..."           # Cohere
export PERPLEXITY_API_KEY="..."       # Perplexity

bash setup.sh --full

All keys are stored securely in ~/.config/opencode/secrets.env with chmod 600 (owner-only read/write).

WSL2-Specific Setup¶

Windows users on WSL2 get automatic optimizations:

What the Script Configures¶

Manual WSL2 Pre-flight¶

Before running setup.sh on WSL2:

# In PowerShell (Admin) — ensure WSL2 is default
wsl --set-default-version 2

# Optional: adjust WSL2 resources
# Edit %USERPROFILE%\.wslconfig:
[wsl2]
memory=8GB
processors=4
localhostForwarding=true
networkingMode=mirrored

Using Chrome in WSL2¶

Chrome is installed with WSL2 compatibility. Use the chrome-open wrapper:

chrome-open                     # Launch Chrome
chrome-open https://github.com  # Open specific URL

WSL2 File Performance¶

• Work in ~/projects/ (Linux filesystem) — not /mnt/c/
• Avoid cross-filesystem operations (10-100x slower)
• The installer sets ~/projects as the default project directory

What Happens During Install¶

The script runs through these stages (32 modules total):

flowchart LR
    A[System Check] --> B[System Packages]
    B --> C[Docker]
    C --> D[Chrome]
    D --> E[ZSH]
    E --> F["Languages (8)"]
    F --> G[OpenCode CLI]
    G --> H["MCP + LSP (24+12)"]
    H --> I[ChromaDB]
    I --> J[LLM Tools]
    J --> K[Project Setup]
    K --> L[Finalize]
    L --> M[Done]

Stage Details¶

Post-Install Verification¶

Verify Everything Works¶

# Full diagnostics (115+ checks across 11 sections)
dev health

# Compare installed versions against latest releases
dev version-check

# List all installed components
dev list

What Health Check Covers¶

First Steps After Install¶

1. Restart your shell or run source ~/.zshrc
2. Set up Git (if not already):

   git config --global user.name "Your Name"
   git config --global user.email "you@example.com"
   

3. Test AI code generation:

   opencode "Create a simple Go web server with /health and /users endpoints"
   

4. Explore MCP servers — they're already configured in opencode.json:

   cat ~/opencode_initializer/opencode.json | python3 -m json.tool | head -80
   

5. Start GPU services (if you have a GPU):

   systemctl --user start ollama
   ollama pull llama3.2    # Pull a 2GB model
   ollama run llama3.2 "Hello, what can you do?"
   

6. Open the Web UI:

   systemctl --user start open-webui
   # Visit http://localhost:3000
   

The dev CLI¶

After installation, a handy dev CLI tool is available:

dev health          # Full diagnostics (115+ checks)
dev version-check   # Compare installed vs latest versions
dev update          # Update all tools
dev list            # List installed components
dev install docker  # Install a new component
dev remove java     # Remove a component
dev config          # Edit setup config
dev autoupdate      # Run full system update (topgrade)
dev self-update     # Update setup.sh itself from GitHub
dev infra           # Manage infrastructure services (start/stop/status)
dev plugins         # Manage OpenCode plugins (install/remove/list)
dev observability   # Grafana + Prometheus monitoring
dev gui             # Web management interface
dev isolated        # Isolated Circuit Mode (on/off/status)
dev models          # Model recommendations and management
dev backup          # Config backup/restore

Common First-Run Scenarios¶

Scenario 1: Fresh Ubuntu/WSL2 — Everything In¶

curl -fsSL https://raw.githubusercontent.com/AlexanderNarbaev/opencode_initializer/main/setup.sh | bash
# Wait 15-20 minutes
# Restart your terminal or source ~/.zshrc
dev health
opencode "What can you help me with?"

Scenario 2: Adding OpenCode to an Existing Machine¶

git clone https://github.com/AlexanderNarbaev/opencode_initializer.git ~/opencode_initializer
cd ~/opencode_initializer
bash setup.sh --interactive
# Select: OpenCode CLI, MCP + LSP, ZSH
# Deselect: languages you already have

Scenario 3: CI/CD Pipeline¶

# In GitHub Actions workflow:
- name: Setup OpenCode CI
  run: |
    curl -fsSL https://raw.githubusercontent.com/AlexanderNarbaev/opencode_initializer/main/setup.sh | bash -s -- --ci

CI mode installs only: OpenCode CLI + Bun + essential MCPs (filesystem, context7). No Docker, no ZSH, no GUI tools.

Scenario 4: Team Member Onboarding¶

# Send this one-liner to new team members:
bash setup.sh --full \
  --deepseek-key "sk-team-key" \
  --github-token "ghp_team-github-token" \
  --gitlab-token "glpat-team-gitlab-token"

See the Team Setup Guide for detailed team onboarding.

Scenario 5: ML/AI Developer with GPU¶

bash setup.sh --full
# GPU auto-detected: NVIDIA → Ollama with CUDA
# Check GPU is working:
nvidia-smi
ollama run llama3.2 "What GPU are you using?"

Common First-Time Issues¶

"Permission denied" on curl|bash¶

Make sure you're not running as root. The script uses sudo internally where needed.

WSL2: DNS not resolving¶

The script adds Google DNS (8.8.8.8, 1.1.1.1) automatically. If still broken:

sudo sh -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf'

If the issue persists after restart:

# In PowerShell (Admin):
wsl --shutdown

"Package not found" on non-Ubuntu systems¶

The script auto-detects your package manager. If it fails, install the equivalent packages manually and re-run.

Chrome won't start in WSL2¶

Chrome is configured with --no-sandbox for WSL2. Use the chrome-open launcher:

chrome-open

MCP servers not starting¶

MCP servers use absolute paths to ~/.bun/bin/. If you see "command not found":

# Reinstall Bun and MCP servers
curl -fsSL https://bun.sh/install | bash
bash setup.sh --reinit

Low disk space during install¶

Skip heavy components:

bash setup.sh --interactive
# Deselect: Docker, Chrome, vLLM, RAG, Open WebUI, Ollama

Next Steps¶

• User Guide — day-to-day usage
• Advanced Guide — customization and WSL2 tuning
• Architecture — understand how it works
• Reference — CLI and config reference
• FAQ — common questions and answers
• Comparison — how OpenCode Initializer compares to alternatives