Home Explore Help
Sign In
logic855
/
OpenAgentsControl
mirror of https://github.com/darrenhinde/OpenAgentsControl.git
1
0
Fork 0
Files Issues 0 Wiki
Tree: bf02ad0d5c
Branches Tags
OpenAgentsCo...
/
docs
/
getting-started
/
installation.md

installation.md 14 KB
History Raw

OpenAgents Control Installation Guide

Complete guide to installing OpenAgents Control components using the automated installer script.

Quick Start

Default Installation (Local Directory)

# Interactive mode - choose components
bash <(curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh)

# Quick install with profile
bash <(curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh) developer

Installs to .opencode/ in your current directory.

Installation Methods

1. Interactive Installation (Recommended for First-Time Users)

Run the installer without arguments to get an interactive experience:

curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash

Interactive Flow:

  1. Choose Installation Location

    • Local (.opencode/ in current directory)
    • Global (~/.config/opencode/)
    • Custom (enter any path)

  2. Choose Installation Mode

    • Quick Install (select a profile)
    • Custom Install (pick individual components)
    • List Available Components

  3. Select Components (if custom mode)

    • Choose from agents, subagents, commands, tools, contexts, config

  4. Review & Confirm

    • See what will be installed
    • Confirm installation directory
    • Proceed or cancel

2. Profile-Based Installation (Quick Setup)

Install a pre-configured set of components:

# Essential - Minimal setup with core agents
bash <(curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh) essential

# Developer - Code-focused development tools
bash <(curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh) developer

# Business - Content and business-focused tools
bash <(curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh) business

# Full - Everything except system-builder
bash <(curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh) full

# Advanced - Complete system with all components
bash <(curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh) advanced

3. Download & Run (For Offline or Repeated Use)

# Download the installer
curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh -o install.sh

# Make it executable
chmod +x install.sh

# Run interactively
./install.sh

# Or with a profile
./install.sh developer

Installation Locations

Local Installation (Default)

Installs to .opencode/ in your current directory.

Best for:

  • Project-specific agents
  • Testing and development
  • Multiple isolated installations
# Default behavior
./install.sh developer

# Explicit local installation
./install.sh developer --install-dir .opencode

Result:

your-project/
├── .opencode/
│   ├── agent/
│   ├── command/
│   ├── context/
│   └── tool/
└── your-project-files...

Global Installation

Installs to ~/.config/opencode/ for user-wide access.

Best for:

  • System-wide agent availability
  • Single installation for all projects
  • Consistent agent versions
# Using CLI argument
./install.sh developer --install-dir ~/.config/opencode

# Using environment variable
export OPENCODE_INSTALL_DIR=~/.config/opencode
./install.sh developer

Result:

~/.config/
└── opencode/
    ├── agent/
    ├── command/
    ├── context/
    └── tool/

Custom Installation

Install to any directory you choose.

Best for:

  • Custom organizational structures
  • Shared team installations
  • Non-standard setups
# Custom path
./install.sh developer --install-dir ~/my-agents

# Path with spaces (use quotes)
./install.sh developer --install-dir "~/My Agents/opencode"

# Absolute path
./install.sh developer --install-dir /opt/opencode

Installation Directory Options

CLI Argument

Use --install-dir to specify installation directory:

# Format 1: --install-dir=PATH
./install.sh developer --install-dir=~/.config/opencode

# Format 2: --install-dir PATH
./install.sh developer --install-dir ~/.config/opencode

Environment Variable

Set OPENCODE_INSTALL_DIR for persistent configuration:

# Set once, use multiple times
export OPENCODE_INSTALL_DIR=~/.config/opencode

# Now all installations use this directory
./install.sh developer
./install.sh --list

Add to your shell profile for persistence:

# ~/.bashrc or ~/.zshrc
export OPENCODE_INSTALL_DIR=~/.config/opencode

Interactive Selection

When running in interactive mode, you'll be prompted to choose:

Choose installation location:

  1) Local - Install to .opencode/ in current directory
     (Best for project-specific agents)
     
  2) Global - Install to ~/.config/opencode/
     (Best for user-wide agents available everywhere)
     
  3) Custom - Enter exact path
     Examples:
       Linux/Mac:  /home/user/my-agents or ~/my-agents
       Windows:    C:/Users/user/my-agents or ~/my-agents
     
Enter your choice [1-3]:

Priority Order

Installation directory is determined by (highest to lowest priority):

  1. --install-dir CLI argument
  2. OPENCODE_INSTALL_DIR environment variable
  3. Interactive selection (if in interactive mode)
  4. Default: .opencode

Platform-Specific Installation

Linux

# Standard installation
curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s developer

# Global installation
./install.sh developer --install-dir ~/.config/opencode

# System-wide (requires sudo)
sudo ./install.sh developer --install-dir /opt/opencode

macOS

# Standard installation
curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s developer

# Global installation (XDG standard)
./install.sh developer --install-dir ~/.config/opencode

# macOS native location
./install.sh developer --install-dir ~/Library/Application\ Support/opencode

Windows (Git Bash)

# Standard installation
curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s developer

# Global installation
./install.sh developer --install-dir ~/.config/opencode

# Windows-style path
./install.sh developer --install-dir C:/Users/username/opencode

Windows (WSL)

# Same as Linux
curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s developer

# Global installation
./install.sh developer --install-dir ~/.config/opencode

Available Profiles

Essential

Minimal setup with core agents

Components:

  • Core agents: openagent
  • Essential contexts
  • Basic configuration
./install.sh essential

Developer

Code-focused development tools

Components:

  • Development agents: openagent, opencoder, task-manager
  • Code subagents: reviewer, tester, coder-agent, build-agent
  • Development commands: test, commit, context
  • Development tools and contexts
./install.sh developer

Business

Content and business-focused tools

Components:

  • Business agents
  • Content creation tools
  • Documentation agents
  • Business contexts
./install.sh business

Full

Everything except system-builder

Components:

  • All agents and subagents
  • All commands
  • All tools
  • All contexts
  • All configuration
./install.sh full

Advanced

Complete system with all components

Components:

  • Everything in Full profile
  • System-builder agents
  • Advanced configuration
  • Complete toolset
./install.sh advanced

Post-Installation

1. Verify Installation

# Check installed files
ls -la .opencode/

# Or for global installation
ls -la ~/.config/opencode/

2. Configure Environment

# Copy example environment file
cp env.example .env

# Edit with your settings
nano .env

3. Start Using OpenCode

# Run OpenCode CLI
opencode

# Or use specific agents/commands
# (depends on your OpenCode CLI setup)

Collision Handling

When installing into an existing directory, the installer detects file collisions and offers 4 options:

Option 1: Skip Existing (Safest)

  • Only install new files
  • Keep all existing files unchanged
  • Your customizations are preserved

Option 2: Overwrite All (Destructive)

  • Replace all existing files with new versions
  • Your customizations will be lost
  • Requires confirmation

Option 3: Backup & Overwrite (Recommended)

  • Backs up existing files to .opencode.backup.{timestamp}/
  • Then installs new versions
  • You can restore from backup if needed

Option 4: Cancel

  • Exit without making changes

See Collision Handling Guide for detailed information.

Updating Installations

Add New Components

# Run installer again with "Skip existing" option
./install.sh developer

# When prompted for collision handling, choose:
# Option 1: Skip existing

Only new components will be installed, existing files remain unchanged.

Update All Components

# Run installer with "Backup & overwrite" option
./install.sh developer

# When prompted for collision handling, choose:
# Option 3: Backup & overwrite

All components updated, backup created for safety.

Migrate to Different Location

# Option 1: Move existing installation
mv .opencode ~/.config/opencode

# Option 2: Fresh install to new location
./install.sh developer --install-dir ~/.config/opencode

Troubleshooting

Dependencies Missing

Error: curl: command not found or jq: command not found

Solution:

# macOS
brew install curl jq

# Ubuntu/Debian
sudo apt-get install curl jq

# Fedora/RHEL
sudo dnf install curl jq

# Arch Linux
sudo pacman -S curl jq

Permission Denied

Error: Permission denied when creating directories

Solution:

# Install to a directory you own
./install.sh developer --install-dir ~/opencode

# Or create parent directory first
mkdir -p ~/.config
./install.sh developer --install-dir ~/.config/opencode

Path with Spaces

Error: Installation fails with paths containing spaces

Solution:

# Quote the path
./install.sh developer --install-dir "~/My Agents/opencode"

Parent Directory Doesn't Exist

Error: Parent directory does not exist

Solution:

# Create parent directory first
mkdir -p ~/.config

# Then install
./install.sh developer --install-dir ~/.config/opencode

Bash Version Too Old

Error: This script requires Bash 3.2 or higher

Solution:

# Check your bash version
bash --version

# macOS: Install newer bash via Homebrew
brew install bash

# Linux: Update bash via package manager
sudo apt-get update && sudo apt-get upgrade bash

Advanced Usage

View Available Components

# List all components without installing
./install.sh --list

Get Help

# Show all options and examples
./install.sh --help

Specify Git Branch

# Install from a different branch
export OPENCODE_BRANCH=develop
./install.sh developer

Non-Interactive Installation (CI/CD)

# Set environment variables for automation
export OPENCODE_INSTALL_DIR=/opt/opencode
export OPENCODE_BRANCH=main

# Run with profile (no prompts)
./install.sh developer

Environment Variables

Variable Description Default Example
OPENCODE_INSTALL_DIR Installation directory .opencode ~/.config/opencode
OPENCODE_BRANCH Git branch to install from main develop

Examples

Example 1: First-Time Local Installation

# Download and run installer
curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s developer

# Result: Installs to .opencode/ in current directory

Example 2: Global Installation for All Projects

# Install to global config directory
./install.sh developer --install-dir ~/.config/opencode

# Now available to all projects

Example 3: Team Shared Installation

# Install to shared directory
sudo ./install.sh full --install-dir /opt/opencode

# Team members can access from /opt/opencode

Example 4: Multiple Installations

# Project A - local installation
cd ~/projects/project-a
./install.sh developer

# Project B - different local installation
cd ~/projects/project-b
./install.sh business

# Each project has its own .opencode/ directory

Example 5: Update Existing Installation

# Run installer again
./install.sh developer

# Choose "Skip existing" to add only new components
# Or "Backup & overwrite" to update everything

Next Steps

After installation:

  1. Review Components

    ls -la .opencode/

  2. Configure Environment

    cp env.example .env
nano .env

  3. Read Documentation

  4. Start Using OpenCode

    opencode

Getting Help

Summary

The OpenAgents Control installer provides:

✅ Flexible installation locations - Local, global, or custom
✅ Multiple installation methods - Interactive, profile-based, or custom
✅ Cross-platform support - Linux, macOS, Windows
✅ Safe updates - Collision detection and backup options
✅ Easy to use - Simple commands, clear prompts

Choose the installation method that fits your needs and get started with OpenAgents Control!