OCCode CLI Administrator Guide

Comprehensive reference for system administrators, team leads, and enterprise deployers managing OCCode CLI deployments.

1. Introduction

1.1 Purpose of This Guide

This Administrator Guide provides complete instructions for deploying, configuring, securing, and managing OCCode CLI across teams and organizations. It covers everything from single-developer setups to enterprise-wide deployments with enforced compliance, centralized auditing, and locked-down configurations.

1.2 Admin vs User Responsibilities

1.3 Architecture Overview

+------------------------------------------------------------------+
|                     OCCode CLI Architecture                       |
+------------------------------------------------------------------+
|                                                                    |
|  +------------------+    +------------------+    +--------------+ |
|  |   User Terminal  |    |   VS Code Ext    |    | Claude / AI  | |
|  |   (REPL / run)   |    |   (OCCode IDE)   |    | Desktop MCP  | |
|  +--------+---------+    +--------+---------+    +------+-------+ |
|           |                       |                      |         |
|           +----------+------------+----------+-----------+         |
|                      |                       |                     |
|              +-------v--------+     +--------v--------+           |
|              |   CLI Engine   |     |   MCP Server    |           |
|              |  (commands,    |     |  (stdio/HTTP    |           |
|              |   AI router,   |     |   transport)    |           |
|              |   sessions)    |     +---------+-------+           |
|              +-------+--------+               |                   |
|                      |                        |                   |
|    +-----------------+------------------------+----------------+  |
|    |                 |                        |                |  |
| +--v---+  +----v-----+  +-------v-------+ +--v---------+     |  |
| |Config|  |  Daemon   |  |   Security    | | Transcript |     |  |
| |Loader|  | (indexer, |  | (auth, rate   | | (encrypted |     |  |
| |(.env)|  |  watcher, |  |  limit, path  | |  masking,  |     |  |
| +------+  |  context) |  |  sandbox)     | |  audit)    |     |  |
|           +-----+-----+  +--------------+ +------------+     |  |
|                 |                                              |  |
|           +-----v-----+                                       |  |
|           |  SQLite    |  ~/.occode/                          |  |
|           |  Index DB  |  (config, sessions, logs, index)     |  |
|           +-----------+                                       |  |
+------------------------------------------------------------------+
|  External:  AI Providers (Anthropic, OpenAI, Google, Ollama...)   |
+------------------------------------------------------------------+

2. Deployment & Distribution

2.1 NPM Package Deployment

The simplest cross-platform distribution method. Requires Node.js 20+ on target machines.

# Prepare package.json
{
  "name": "@occode/cli",
  "version": "0.1.0",
  "bin": {
    "occode": "./bin/occode.js"
  },
  "files": ["dist/", "bin/", "README.md", "LICENSE"]
}

# Build, test, and publish
npm run build
npm link
occode --help

# Package for distribution
# Users download from opencan.ai/downloads (account required)
# and activate with: occode activate --key LICENSE-KEY

2.2 Native Binary Builds with pkg

Create standalone executables with an embedded Node.js runtime.

# Install pkg
npm install -g pkg

# Add pkg config to package.json
"pkg": {
  "scripts": ["dist/**/*.js"],
  "assets": ["node_modules/**/*"],
  "targets": [
    "node18-win-x64",
    "node18-macos-x64",
    "node18-macos-arm64",
    "node18-linux-x64"
  ],
  "outputPath": "build"
}

# Build for all platforms
npm run build
pkg . --out-path build/

# Output:
# build/occode-win.exe        (Windows x64)
# build/occode-macos          (macOS Intel)
# build/occode-macos-arm64    (macOS Apple Silicon)
# build/occode-linux          (Linux x64)

# Optional: compress with UPX
upx --best build/occode-win.exe
upx --best build/occode-linux

2.3 Platform-Specific Installers

Windows - NSIS Installer

# occode-installer.nsi
!define APP_NAME "OCCode CLI"
!define APP_VERSION "0.1.0"
!define PUBLISHER "OpenCan.ai"

OutFile "occode-setup-${APP_VERSION}.exe"
InstallDir "$PROGRAMFILES64\OCCode"

Section "Install"
  SetOutPath "$INSTDIR"
  File "build\occode-win.exe"
  EnVar::SetHKCU
  EnVar::AddValue "PATH" "$INSTDIR"
  WriteUninstaller "$INSTDIR\uninstall.exe"
  WriteRegStr HKLM \
    "Software\Microsoft\Windows\CurrentVersion\Uninstall\OCCode" \
    "DisplayName" "OCCode CLI"
  WriteRegStr HKLM \
    "Software\Microsoft\Windows\CurrentVersion\Uninstall\OCCode" \
    "UninstallString" "$INSTDIR\uninstall.exe"
SectionEnd

Section "Uninstall"
  Delete "$INSTDIR\occode-win.exe"
  Delete "$INSTDIR\uninstall.exe"
  RMDir "$INSTDIR"
  DeleteRegKey HKLM \
    "Software\Microsoft\Windows\CurrentVersion\Uninstall\OCCode"
SectionEnd

# Build: makensis occode-installer.nsi

macOS - .pkg Installer

#!/bin/bash
# build-mac-pkg.sh
VERSION="0.1.0"
IDENTIFIER="ai.opencan.occode"

mkdir -p package/usr/local/bin
cp build/occode-macos package/usr/local/bin/occode
chmod +x package/usr/local/bin/occode

pkgbuild \
  --root package \
  --identifier "$IDENTIFIER" \
  --version "$VERSION" \
  --install-location / \
  occode-$VERSION.pkg

rm -rf package

Linux - .deb Package (Debian/Ubuntu)

#!/bin/bash
# build-deb.sh
VERSION="0.1.0"
ARCH="amd64"
PKG_NAME="occode_${VERSION}_${ARCH}"

mkdir -p $PKG_NAME/DEBIAN
mkdir -p $PKG_NAME/usr/local/bin
cp build/occode-linux $PKG_NAME/usr/local/bin/occode
chmod +x $PKG_NAME/usr/local/bin/occode

cat > $PKG_NAME/DEBIAN/control << EOF
Package: occode
Version: $VERSION
Section: devel
Priority: optional
Architecture: $ARCH
Maintainer: OpenCan.ai <support@opencan.ai>
Description: OCCode - AI-powered coding assistant
EOF

dpkg-deb --build $PKG_NAME

# Install: sudo dpkg -i occode_0.1.0_amd64.deb

Linux - .rpm Package (Red Hat/Fedora)

# ~/rpmbuild/SPECS/occode.spec
Name:           occode
Version:        0.1.0
Release:        1%{?dist}
Summary:        OCCode - AI-powered coding assistant
License:        MIT
URL:            https://opencan.ai

%description
Terminal-based AI coding assistant with multi-provider support.

%install
mkdir -p %{buildroot}/usr/local/bin
install -m 755 %{SOURCE0} %{buildroot}/usr/local/bin/occode

%files
/usr/local/bin/occode

# Build: rpmbuild -ba ~/rpmbuild/SPECS/occode.spec
# Install: sudo rpm -i occode-0.1.0-1.x86_64.rpm

Linux - AppImage (Universal)

mkdir -p OCCode.AppDir/usr/bin
cp build/occode-linux OCCode.AppDir/usr/bin/occode

cat > OCCode.AppDir/occode.desktop << EOF
[Desktop Entry]
Type=Application
Name=OCCode
Exec=occode
Icon=occode
Categories=Development;
Terminal=true
EOF

cat > OCCode.AppDir/AppRun << 'EOF'
#!/bin/bash
exec "${APPDIR}/usr/bin/occode" "$@"
EOF
chmod +x OCCode.AppDir/AppRun

./appimagetool-x86_64.AppImage OCCode.AppDir occode-0.1.0-x86_64.AppImage

2.4 Docker Deployment

# Dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist/ ./dist/
COPY bin/ ./bin/
RUN npm link
ENTRYPOINT ["occode"]
CMD ["--help"]

# Build and publish
docker build -t opencan/occode:0.1.0 .
docker tag opencan/occode:0.1.0 opencan/occode:latest
docker push opencan/occode:0.1.0
docker push opencan/occode:latest

# Users run with:
docker run -it --rm -v $(pwd):/workspace opencan/occode run "task"

2.5 Distribution via opencan.ai

# OCCode is distributed exclusively through opencan.ai/downloads
# Users must:
# 1. Create an account at opencan.ai
# 2. Download the archive for their platform
# 3. Extract and install the binary
# 4. Activate with their license key:
#    occode activate --key YOUR-LICENSE-KEY

# Supported platforms:
# - Windows x64:        occode-0.1.0-windows-x64.zip
# - macOS Intel:        occode-0.1.0-macos-x64.tar.gz
# - macOS Apple Silicon: occode-0.1.0-macos-arm64.tar.gz
# - Linux x64:          occode-0.1.0-linux-x64.tar.gz

2.6 Release Build CI/CD Pipeline

# .github/workflows/release.yml
name: Release
on:
  push:
    tags: ['v*']

jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run build
      - run: |
          npm install -g pkg
          pkg . --targets node18-${{ matrix.os }}-x64
      - uses: actions/upload-artifact@v3
        with:
          name: occode-${{ matrix.os }}
          path: build/

  release:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v3
      - uses: softprops/action-gh-release@v1
        with:
          files: |
            **/*.exe
            **/*.tar.gz
            **/*.zip

2.7 Complete Build Script (build-all.sh)

#!/bin/bash
VERSION="0.1.0"
echo "Building OCCode CLI v$VERSION for all platforms..."

rm -rf dist build && mkdir -p build

echo "Building TypeScript..."
npm run build

echo "Building native binaries..."
pkg . --out-path build/

mv build/occode-win.exe     build/occode-${VERSION}-win-x64.exe
mv build/occode-macos       build/occode-${VERSION}-macos-x64
mv build/occode-macos-arm64 build/occode-${VERSION}-macos-arm64
mv build/occode-linux       build/occode-${VERSION}-linux-x64

echo "Compressing..."
command -v upx &> /dev/null && {
  upx --best build/*.exe 2>/dev/null || true
  upx --best build/*-linux-* 2>/dev/null || true
}

cd build
zip    occode-${VERSION}-win-x64.zip         occode-${VERSION}-win-x64.exe
tar -czf occode-${VERSION}-macos-x64.tar.gz  occode-${VERSION}-macos-x64
tar -czf occode-${VERSION}-macos-arm64.tar.gz occode-${VERSION}-macos-arm64
tar -czf occode-${VERSION}-linux-x64.tar.gz  occode-${VERSION}-linux-x64
cd ..

echo "Build complete!"
ls -lh build/

2.8 Distribution Checklist

3. Team & Enterprise Configuration

3.1 Account Types

3.2 .env.team File Setup

The .env.team file is the primary mechanism for administrators to enforce organization-wide settings. Team settings always override user settings.

File Locations (in order of precedence)

# Example: /etc/occode/.env.team
OCCODE_ACCOUNT_TYPE=team
OCCODE_TEAM_ID=engineering
OCCODE_TEAM_NAME=Engineering Team

# Provider enforcement
OCCODE_REQUIRED_PROVIDER=anthropic
OCCODE_REQUIRED_MODEL=claude-sonnet-4.5
OCCODE_LOCK_PROVIDER=true
ANTHROPIC_API_KEY=sk-ant-team-key-...

# Centralized transcripts
OCCODE_TEAM_TRANSCRIPT_PASSWORD=team-secure-password-16chars
OCCODE_TEAM_TRANSCRIPT_DIR=/mnt/audit/occode-transcripts
OCCODE_LOCK_TRANSCRIPT_DIR=true
OCCODE_AUTO_ENABLE_TRANSCRIPTS=true
OCCODE_ENFORCE_TRANSCRIPTS=false

# Security and compliance
OCCODE_REQUIRE_MFA=false
OCCODE_AUDIT_RETENTION_DAYS=90
OCCODE_MAX_SESSION_DURATION=0

# Feature toggles
OCCODE_ENABLE_SANDBOX=true
OCCODE_ENABLE_DAEMON=true

3.3 Configuration Precedence

# Example: User sets their own transcript dir
# In .env (user)
OCCODE_TRANSCRIPT_DIR=~/my-transcripts

# In .env.team (admin)
OCCODE_TEAM_TRANSCRIPT_DIR=/mnt/audit/transcripts
OCCODE_LOCK_TRANSCRIPT_DIR=true

# Result: /mnt/audit/transcripts (team setting wins)

3.4 Locking Provider Settings

# In .env.team - force all users to use a specific provider
OCCODE_LOCK_PROVIDER=true
OCCODE_REQUIRED_PROVIDER=anthropic
OCCODE_REQUIRED_MODEL=claude-sonnet-4.5
OCCODE_TEAM_API_URL=https://api.company.com/v1   # Optional self-hosted proxy

When OCCODE_LOCK_PROVIDER=true is set, users cannot change the provider with /provider or /model commands.

3.5 Role-Based Access Control

3.6 Account Configuration File

# ~/.occode/account.json
{
  "type": "team",
  "userId": "john",
  "userRole": "admin",
  "teamId": "acme-corp",
  "teamName": "Acme Corporation",
  "transcriptSettings": {
    "enabled": true,
    "enforcedByAdmin": true
  }
}

4. Security Administration

4.1 MCP Security Setup

# Step 1: Initialize security configuration
occode
/mcp init
# Creates ~/.occode/config/security.yaml and ~/.occode/logs/

# Step 2: Generate an API key
/mcp keygen

# Step 3: Edit security config to add the key
/mcp config
# Opens ~/.occode/config/security.yaml in your default editor

4.2 Security Configuration Reference (security.yaml)

# ~/.occode/config/security.yaml - Full Reference
security:
  enabled: true

  authentication:
    require_auth: true
    api_keys:
      - key: "occode_ak_1234567890abcdef..."
        role: "admin"
        name: "Admin Bot"
        enabled: true
      - key: "occode_ak_abcdef1234567890..."
        role: "developer"
        name: "Dev CI Pipeline"
        enabled: true
      - key: "occode_ak_viewer123..."
        role: "viewer"
        name: "Read-only Monitor"
        enabled: true
    allowed_ips:
      - "10.0.0.0/8"
      - "192.168.1.0/24"

  command_execution:
    enabled: true
    whitelist_mode: true
    allowed_commands:
      - git
      - npm
      - yarn
      - pnpm
      - node
      - tsc
      - eslint
      - prettier
      - cargo
      - go
      - python
      - python3
      - pytest
      - ls
      - cat
      - grep
      - mkdir
      - echo
      - pwd
      - which
    blocked_patterns:
      - "rm\\s+-rf\\s+/"
      - "sudo"
      - "curl.*\\|.*sh"
      - "/etc/passwd"
      - "dd\\s+"
      - "mkfs"
      - "reboot"
      - "shutdown"
      - "chmod\\s+777"
      - "eval\\s+"
      - "exec\\s+"
    max_timeout: 60000

  file_operations:
    enabled: true
    allowed_directories:
      - "/home/user/projects"
      - "/var/www"
    blocked_directories:
      - "/etc"
      - "/usr"
      - "/sys"
      - "/proc"
    max_file_size: 10485760   # 10MB

  rate_limits:
    commands_per_minute: 100
    files_per_minute: 200
    commands_per_day: 10000

  audit:
    enabled: true
    log_path: "~/.occode/logs/audit.log"
    alert_on_failures: true
    alert_webhook: ""

  sandboxing:
    enabled: false
    cpu_limit_percent: 90
    memory_limit_mb: 512
    network_access: "full"    # full | restricted | none

4.3 Authentication & API Keys

API keys are generated with /mcp keygen and assigned to roles:

4.4 Command Whitelisting & Blocked Patterns

When whitelist_mode: true, only commands in allowed_commands can execute. Additionally, commands matching blocked_patterns are always rejected.

Default Blocked Commands

• rm -rf / - Dangerous recursive deletion
• sudo - Privilege escalation
• curl | sh - Remote code execution
• /etc/passwd - System file access
• dd, mkfs - Disk operations
• reboot, shutdown - System control
• chmod 777 - Dangerous permission changes
• eval, exec - Dynamic code execution

4.5 Path Sandboxing

file_operations:
  allowed_directories:
    - "/home/user/projects"    # Only these dirs accessible
    - "/var/www/myapp"
  blocked_directories:
    - "/etc"                   # Always blocked
    - "/usr"
    - "/sys"
    - "/proc"

4.6 Rate Limiting

rate_limits:
  commands_per_minute: 100
  files_per_minute: 200
  commands_per_day: 10000

4.7 Docker Sandbox Mode

Optional container-based isolation for maximum security.

# Default Docker sandbox settings
Image:    node:20-alpine
Network:  none              # No network access
Memory:   512m
CPUs:     1.0
Timeout:  60 seconds
PIDs:     50 max
Privs:    no-new-privileges

# Enable:
OCCODE_ENABLE_SANDBOX=true

4.8 Resource Limits

4.9 Command Sanitization

The CommandSanitizer prevents shell injection by:

• Parsing commands without shell interpretation when possible
• Blocking shell metacharacters (; & | ` $ ( ) { })
• Filtering dangerous environment variables (LD_PRELOAD, DYLD_INSERT_LIBRARIES)
• Providing a safe environment with minimal variables (PATH, HOME, USER, LANG, TERM)
• Validating executables against a safe list before direct execution

4.10 Execution Modes & Permission Matrix

5. Transcript & Audit Management

5.1 Personal vs Team Transcripts

5.2 Centralized Transcript Configuration

# /etc/occode/.env.team

# Team encryption password (12-20 characters)
OCCODE_TEAM_TRANSCRIPT_PASSWORD=team-secure-password-16chars

# Centralized directory
OCCODE_TEAM_TRANSCRIPT_DIR=/mnt/audit/occode-transcripts

# Lock the directory
OCCODE_LOCK_TRANSCRIPT_DIR=true

# Auto-enable transcripts on session start
OCCODE_AUTO_ENABLE_TRANSCRIPTS=true

# Enforce: users cannot disable transcripts
OCCODE_ENFORCE_TRANSCRIPTS=true

5.3 Automatic Key Masking

All sensitive data is automatically masked as ****** in transcripts. This cannot be disabled.

5.4 Timestamp Format for Auditing

# Every prompt includes timestamps:
# 2026-01-28 11:49:07 EST > your prompt here

# Format: YYYY-MM-DD HH:MM:SS TZ
# Exported JSON includes both formats:
{
  "timestamp": "2026-01-28 11:49:15 EST",
  "timestampRaw": 1706464155000,
  "role": "user",
  "content": "What is the deployment status?",
  "metadata": null
}

5.5 Transcript Commands

/transcripts                # Toggle transcript saving
/transcripts status         # Show status and configuration
/transcripts dir            # Show directory configuration
/transcripts export [path]  # Export to JSON (keys auto-masked)
/transcripts clear          # Clear all entries

5.6 Audit Logging & Viewing

# View MCP audit logs
/mcp logs          # Last 50 entries
/mcp logs 100      # Last 100 entries

# Direct file access
tail -50 ~/.occode/logs/audit.log

# Each entry includes: timestamp, API key (masked),
# operation, resource, success/failure, error, IP

5.7 Compliance Considerations

6. Daemon Administration

6.1 Daemon Architecture

The OCCode daemon provides persistent codebase indexing, real-time file watching, and shared state between sessions.

+------------------------------------------------------------+
|                    OCCode Daemon                            |
|  (Background process - serves all CLI sessions)            |
+------------------------------------------------------------+
|                                                              |
|  +--------------+  +--------------+  +--------------+       |
|  |  Codebase    |  |    File      |  |   Context    |       |
|  |   Indexer    |  |   Watcher    |  |    Store     |       |
|  |  (SQLite)    |  |  (chokidar)  |  |   (JSON)     |       |
|  +--------------+  +--------------+  +--------------+       |
|         |                |                |                  |
|         +--------+-------+--------+-------+                  |
|                  |                                            |
|         +--------v---------+                                 |
|         | Unix Socket IPC  |                                 |
|         | /tmp/occode-daemon.sock                            |
|         +--------+---------+                                 |
+------------------|-------------------------------------------+
                   |
    +--------------+---+-----------+
    |              |               |
+---v---+   +-----v----+   +-----v-----+
|  CLI  |   |  CLI Run  |   |  VS Code  |
|  REPL |   |  Session  |   | Extension |
+-------+   +----------+   +-----------+

6.2 File Locations

6.3 Starting / Stopping / Restarting

/daemon status    # Check daemon status
/daemon start     # Start daemon manually
/daemon stop      # Stop daemon
/daemon restart   # Restart daemon

6.4 Daemon Auto-Start Configuration

# In .env or .env.team
OCCODE_DAEMON_AUTOSTART=true
OCCODE_DAEMON_PORT=9876
OCCODE_ENABLE_DAEMON=true

6.5 Index Management

/index status     # Show index statistics
/index rebuild    # Force complete rebuild
/index force      # Force rebuild (alias)

Supports: TypeScript, JavaScript, Python, Rust, Go. Uses SQLite with FTS5 full-text search. Updates are incremental based on file hashes.

6.6 Log File Monitoring

tail -f ~/.occode/daemon.log
grep -i error ~/.occode/daemon.log | tail -20

6.7 Troubleshooting Daemon Issues

7. MCP Server Administration

7.1 MCP Server Commands

7.2 Claude Desktop Integration

# macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
# Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "occode": {
      "command": "occode",
      "args": ["mcp", "serve", "/path/to/your/project"],
      "env": {
        "MCP_API_KEY": "your_api_key_here"
      }
    }
  }
}

7.3 OpenClaw Integration

# openclaw-skills/occode.yaml
name: occode
description: OCCode MCP server for code operations
command: occode
args:
  - mcp
  - serve
  - ${WORKSPACE}
env:
  MCP_API_KEY: ${OCCODE_API_KEY}

7.4 Role-Based MCP Permissions

7.5 Available MCP Tools (8 Tools)

7.6 Disabling Security for Local Development

# Option 1: Edit config
# ~/.occode/config/security.yaml
security:
  enabled: false

# Option 2: Environment variable
export MCP_SECURITY_ENABLED=0

8. License & Subscription Management

8.1 Subscription Plans

One license key works for both OCCode CLI and OCCode IDE.

License Key Format

Pro:        OCCODE-PRO--XXXX-XXXX-XXXX
Team:       OCCODE-TEAM-XXXX-XXXX-XXXX
Business:   OCCODE-BUSI-XXXX-XXXX-XXXX
Enterprise: OCCODE-ENTP-XXXX-XXXX-XXXX

8.2 7-Day Free Trial

• Duration: 7 days from first launch
• Features: All features unlocked (including RAG)
• Payment method collected at signup but account is not charged until day 8
• Warnings: Warning shown when 3 or fewer days remain
• Cancellation: Cancel anytime before day 8 without being charged
• Refund Policy: No refunds after billing. Users can cancel before day 8 to avoid charges.

8.3 License Activation

/subscription activate OCCODE-TEAM-XXXX-XXXX-XXXX
/subscription status
/subscription plans

8.4 Trial Expiration Behavior

Refund Policy: No refunds are issued after billing. Since all users receive a full 7-day free trial where their account is not charged, refunds are not offered once the subscription has been charged. Users may cancel anytime before day 8 without being charged. After billing, users may cancel to prevent future charges but will not receive a refund for the current billing period.

8.5 RAG Trial Features & Plans

9. Environment Variables Reference

9.1 Provider Configuration

9.2 API Keys (All 9 Providers)

9.3 Team / Organization Settings

9.4 Transcript Settings

9.5 Security & Compliance

9.6 Feature Toggles

9.7 Debug / Development

9.8 RAG Settings

9.9 Daemon Settings

10. File System Reference

10.1 User Home Directory (~/.occode/)

~/.occode/
  config.json             # Global settings (provider, model, features)
  profiles.json           # Model profiles (named configurations)
  convergence.json        # Multi-LLM convergence settings
  subscription.json       # Trial status and subscription info
  account.json            # Account type, role, team info
  daemon.pid              # Daemon process ID
  daemon.log              # Daemon log output
  config/
    security.yaml         # MCP security configuration
  sessions/
    <session-id>.json    # Saved conversation sessions
  checkpoints/
    <checkpoint-id>/     # File state snapshots
  logs/
    audit.log             # MCP security audit log
  index/
    <project>_<hash>.db # SQLite codebase index per project
  context/
    <hash>.json          # Pinned files and exclusions per project
  transcripts/
    <session>.enc        # Encrypted transcript files
  rag_cache/
    <hash>.cache         # Local RAG embedding cache
  .env.team               # User-level team config (fallback)

10.2 Project-Level Files

10.3 System-Level Files

11. Monitoring & Maintenance

11.1 Health Checks

/daemon status              # Daemon running?
/mcp status                 # MCP server status
/subscription status        # Subscription valid?
occode config --list        # Current config
/transcripts status         # Transcript config
/transcripts dir            # Directory info

# Verify env vars loaded:
printenv | grep OCCODE              # Linux/macOS
Get-ChildItem Env: | Where-Object {$_.Name -like "OCCODE*"}  # Windows

11.2 Log Rotation

# Manual rotation:
mv ~/.occode/daemon.log ~/.occode/daemon.log.1
/daemon restart

mv ~/.occode/logs/audit.log ~/.occode/logs/audit.log.$(date +%Y%m%d)

# Automated with logrotate (Linux):
# /etc/logrotate.d/occode
/home/*/.occode/daemon.log {
  weekly
  rotate 4
  compress
  missingok
  notifempty
  copytruncate
}

/home/*/.occode/logs/audit.log {
  monthly
  rotate 12
  compress
  missingok
  notifempty
  copytruncate
}

11.3 Index Maintenance

/index status               # Check stats
/index rebuild              # Rebuild if corrupt
rm -rf ~/.occode/index/     # Delete all indexes
ls -lh ~/.occode/index/     # Check file sizes

11.4 Session Cleanup

# List sessions
ls -lt ~/.occode/sessions/ | head -20

# Remove sessions older than 30 days
find ~/.occode/sessions/ -name "*.json" -mtime +30 -delete

# Remove old checkpoints
find ~/.occode/checkpoints/ -maxdepth 1 -mtime +14 -exec rm -rf {} +

11.5 Backup Strategies

#!/bin/bash
# Quick backup script
BACKUP_DIR="/backup/occode/$(date +%Y%m%d)"
mkdir -p "$BACKUP_DIR"

cp ~/.occode/config.json "$BACKUP_DIR/"
cp ~/.occode/profiles.json "$BACKUP_DIR/" 2>/dev/null
cp ~/.occode/convergence.json "$BACKUP_DIR/" 2>/dev/null
cp ~/.occode/subscription.json "$BACKUP_DIR/" 2>/dev/null
cp ~/.occode/account.json "$BACKUP_DIR/" 2>/dev/null
cp ~/.occode/config/security.yaml "$BACKUP_DIR/" 2>/dev/null
cp -r ~/.occode/transcripts/ "$BACKUP_DIR/transcripts/" 2>/dev/null
cp ~/.occode/logs/audit.log "$BACKUP_DIR/" 2>/dev/null

echo "Backup complete: $BACKUP_DIR"

11.6 Performance Tuning

• Reduce index size: Use exclusion patterns for node_modules, .git, dist, build
• Limit context tokens: Use /context to monitor usage. Pin only essential files.
• Daemon memory: Very large repos (100k+ files) may use significant memory. Limit watched directories.
• Rate limit tuning: Increase commands_per_minute for CI/CD pipelines.

12. Server Migration Guide

12.1 Monorepo Structure

opencan-server/
  shared/                    # Shared between CLI and Server
    types/                   # Type definitions
    models/                  # Data models
    validation/              # Validation logic
  backend/                   # Server backend (Node.js/Express)
    api/                     # REST API endpoints
    auth/                    # SSO, OAuth, SAML
    services/                # Business logic
    database/                # DB models and migrations
    security/                # Auth, permissions, rate limiting
  frontend/                  # Dashboard UI (React/Next.js)
    components/
    pages/
    api/

12.2 Files to Extract

12.3 Database Migration (File to PostgreSQL)

# Install Prisma ORM
npm install prisma @prisma/client
npx prisma init

# Example schema
model User {
  id        String   @id @default(uuid())
  email     String   @unique
  name      String
  role      String   @default("member")
  teamId    String?
  team      Team?    @relation(fields: [teamId], references: [id])
  createdAt DateTime @default(now())
}

model Team {
  id            String   @id @default(uuid())
  name          String
  members       User[]
  createdAt     DateTime @default(now())
}

model Subscription {
  id        String   @id @default(uuid())
  plan      String
  status    String
  expiresAt DateTime
  teamId    String?  @unique
}

model AuditLog {
  id        String   @id @default(uuid())
  userId    String
  operation String
  resource  String?
  success   Boolean
  createdAt DateTime @default(now())
}

# Run migrations
npx prisma migrate dev --name init

12.4 SSO Integration

# Supported providers:
# - OAuth 2.0 (Google, GitHub, GitLab)
# - SAML      (Okta, Azure AD, OneLogin)
# - OIDC      (OpenID Connect)

npm install passport passport-oauth2 passport-saml jsonwebtoken

# Environment variables:
OKTA_CLIENT_ID="..."
OKTA_CLIENT_SECRET="..."
OKTA_DOMAIN="..."
AZURE_AD_CLIENT_ID="..."
AZURE_AD_CLIENT_SECRET="..."
AZURE_AD_TENANT="..."

12.5 REST API Endpoints

12.6 Docker Compose for Development

# docker-compose.yml
version: '3.8'
services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: opencan
      POSTGRES_USER: opencan
      POSTGRES_PASSWORD: password
    ports:
      - "5432:5432"

  redis:
    image: redis:7
    ports:
      - "6379:6379"

  backend:
    build: ./backend
    environment:
      DATABASE_URL: postgresql://opencan:password@postgres:5432/opencan
      REDIS_URL: redis://redis:6379
      JWT_SECRET: your-secret-key
    ports:
      - "3000:3000"
    depends_on:
      - postgres
      - redis

  frontend:
    build: ./frontend
    environment:
      NEXT_PUBLIC_API_URL: http://backend:3000
    ports:
      - "3001:3001"
    depends_on:
      - backend

12.7 Migration Timeline

13. Troubleshooting for Admins

13.1 Daemon Won't Start

# Check for stale PID file
cat ~/.occode/daemon.pid
# If PID doesn't correspond to running process:
rm ~/.occode/daemon.pid

# Check for stale socket
rm /tmp/occode-daemon.sock

# Check logs
tail -50 ~/.occode/daemon.log

# Restart
/daemon start

13.2 MCP Server Issues

# Verify config exists and is valid
cat ~/.occode/config/security.yaml

# Re-initialize if corrupt
/mcp init

# Check port conflicts
lsof -i :9876              # Linux/macOS
netstat -ano | findstr :9876  # Windows

/mcp status

13.3 Permission Denied Errors

# Check API key role
/mcp keys

# Change role in security.yaml
/mcp config

# Fix ~/.occode/ permissions
chmod 700 ~/.occode/
chmod 600 ~/.occode/config/security.yaml

13.4 Rate Limit Configuration

# Edit ~/.occode/config/security.yaml
rate_limits:
  commands_per_minute: 200    # Increase for CI/CD
  files_per_minute: 500
  commands_per_day: 50000

13.5 Config Not Loading

# Debug config loading
OCCODE_DEBUG=true occode

# Check team config locations
ls -la /etc/occode/.env.team
ls -la ~/.occode/.env.team
ls -la .env.team

# Precedence: .env.team > .env > process.env > defaults

/transcripts status
/transcripts dir

13.6 Transcript Directory Issues

# Check directory exists and is writable
ls -la /mnt/audit/occode-transcripts/

# Create if missing
sudo mkdir -p /mnt/audit/occode-transcripts/
sudo chown -R $USER:$GROUP /mnt/audit/occode-transcripts/
chmod 770 /mnt/audit/occode-transcripts/

13.7 Index Corruption

# Force rebuild
/index rebuild

# If rebuild fails:
rm -rf ~/.occode/index/
/daemon restart
/index rebuild

14. Security Best Practices

14.1 Never Commit .env Files

# .gitignore
.env
.env.local
.env.team
.occode.json

14.2 Use Strong Passwords

• Transcript passwords: 12-20 characters with upper/lower/numbers/symbols
• Use a password manager for team passwords
• Rotate team transcript passwords quarterly

14.3 Centralize Team Secrets

# Store team API keys in /etc/occode/.env.team
# Benefits:
# - Users don't need individual API keys
# - Keys managed in one place
# - Rotation by admin without user involvement

sudo chmod 644 /etc/occode/.env.team
sudo chown root:occode-users /etc/occode/.env.team

14.4 Regular Backups

• Back up security.yaml after every change
• Back up centralized transcript directories daily
• Back up audit logs before rotation
• Store backups in a separate, encrypted location

14.5 Audit Access Regularly

/mcp logs 200

# Look for:
# - Failed authentication attempts
# - Blocked command executions
# - Path validation failures
# - Unusual access patterns

14.6 Lock Critical Settings

# In .env.team
OCCODE_LOCK_PROVIDER=true
OCCODE_LOCK_TRANSCRIPT_DIR=true
OCCODE_ENFORCE_TRANSCRIPTS=true

14.7 MFA for Enterprise

# Enable in .env.team
OCCODE_REQUIRE_MFA=true

# Requires SSO provider with MFA (Okta, Azure AD)

14.8 Secure API Key Storage

# Preferred: Use system keychain
occode config --set-key --provider anthropic

# Stores in:
# Windows:  Credential Manager
# macOS:    Keychain
# Linux:    Secret Service (gnome-keyring, kwallet)

# If using .env files on shared machines:
chmod 600 .env

15. Setup Examples

15.1 Individual Developer

# .env (in project root)
OCCODE_DEFAULT_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-api03-...
OCCODE_TRANSCRIPT_PASSWORD=my-secure-password
OCCODE_DEBUG=false

# Quick start: download from opencan.ai/downloads, then:
occode activate --key YOUR-LICENSE-KEY
occode
/provider anthropic
/model claude-sonnet-4.5

15.2 Team with Centralized Transcripts

# Admin creates: /etc/occode/.env.team
OCCODE_ACCOUNT_TYPE=team
OCCODE_TEAM_ID=engineering
OCCODE_TEAM_NAME=Engineering Team
OCCODE_REQUIRED_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-team-key-...
OCCODE_TEAM_TRANSCRIPT_PASSWORD=team-secret-password-16chars
OCCODE_TEAM_TRANSCRIPT_DIR=/mnt/audit/occode-transcripts
OCCODE_LOCK_TRANSCRIPT_DIR=true
OCCODE_AUTO_ENABLE_TRANSCRIPTS=true

# Admin creates directory:
sudo mkdir -p /mnt/audit/occode-transcripts
sudo chown root:engineering /mnt/audit/occode-transcripts
sudo chmod 770 /mnt/audit/occode-transcripts

# Team members download from opencan.ai/downloads, then:
occode activate --key TEAM-LICENSE-KEY
occode   # Transcripts auto-enabled, provider pre-configured

15.3 Enterprise with Enforced Compliance

# /etc/occode/.env.team (Linux) or C:\ProgramData\occode\.env.team (Windows)
OCCODE_ACCOUNT_TYPE=enterprise
OCCODE_TEAM_ID=acme-corp
OCCODE_TEAM_NAME=Acme Corporation
OCCODE_LOCK_PROVIDER=true
OCCODE_REQUIRED_PROVIDER=anthropic
OCCODE_REQUIRED_MODEL=claude-sonnet-4.5
OCCODE_TEAM_API_URL=https://ai-proxy.acme.com/v1
OCCODE_TEAM_TRANSCRIPT_PASSWORD=enterprise-strong-password!
OCCODE_TEAM_TRANSCRIPT_DIR=\\fileserver\compliance\occode
OCCODE_LOCK_TRANSCRIPT_DIR=true
OCCODE_AUTO_ENABLE_TRANSCRIPTS=true
OCCODE_ENFORCE_TRANSCRIPTS=true
OCCODE_REQUIRE_MFA=true
OCCODE_AUDIT_RETENTION_DAYS=365
OCCODE_MAX_SESSION_DURATION=480
OCCODE_ENABLE_SANDBOX=true

15.4 Self-Hosted with Ollama

# .env
OCCODE_PROVIDER=ollama
OCCODE_MODEL=llama3.3
OCCODE_API_ENDPOINT=http://localhost:11434/v1

# No API key needed - no data leaves the network

# Start Ollama first:
ollama serve
ollama pull llama3.3

# Then:
occode
/provider local
/model llama3.3

15.5 CI/CD Pipeline Integration

# .github/workflows/ai-review.yml
name: AI Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install OCCode
        run: |
          curl -fsSL -H "Authorization: Bearer ${{ secrets.OCCODE_DOWNLOAD_TOKEN }}" \
            https://opencan.ai/downloads/occode-latest-linux-x64.tar.gz | tar xz
          sudo mv occode /usr/local/bin/
          occode activate --key ${{ secrets.OCCODE_LICENSE_KEY }}
      - name: Run AI Review
        env:
          OCCODE_PROVIDER: anthropic
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          OCCODE_MODEL: claude-sonnet-4.5
          MCP_SECURITY_ENABLED: "0"
        run: |
          occode run "Review the git diff" \
            --mode autonomous --max-turns 5

# Docker-based CI/CD:
docker run --rm \
  -v $(pwd):/workspace \
  -e OCCODE_PROVIDER=anthropic \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  opencan/occode:latest run "Run tests and fix failures"

OCCode CLI Administrator Guide — Version 1.0 — February 2026
Published by OpenCan.ai — https://opencan.ai
Support: support@opencan.ai

Contact · Privacy · Terms · Back to OpenCan.ai