Installation Script Support for Containered Environments

[theepicsaxguy]

Summary

Enable users to configure installation/setup scripts that run automatically when setting up repositories or worktrees in containerized environments, similar to how OpenAI Codex handles environment setup scripts.

Problem Statement

When using OpenCode Manager with containerized or remote environments (worktrees), users need a way to:

1. Install dependencies (e.g., npm install, pip install -r requirements.txt, go mod download)
2. Run initial build steps (e.g., npm run build, cargo build)
3. Configure environment-specific setup

Currently, there's no built-in mechanism to automate these setup steps when:

• Cloning a new repository
• Creating a new worktree
• Starting a container/environment for a repository

This creates friction similar to what Codex addresses with their local environments feature.

Reference: How OpenAI Codex Implements This

Codex stores setup scripts in .codex/config.toml with the following structure:

# Setup scripts run when creating a new worktree
[setup]
# Default script (runs on all platforms)
script = """
npm install
npm run build
"""

# Platform-specific overrides
[setup.macos]
script = """brew install pkg"""

[setup.windows]
script = """choco install pkg"""

[setup.linux]
script = """apt-get install pkg"""

# Actions - common tasks accessible in the UI
[[actions]]
name = "Run"
icon = "play"
script = "npm start"

[[actions]]
name = "Test"
icon = "beaker"
script = "npm test"

Key Codex behaviors:

• Setup scripts run automatically when creating a new worktree
• Scripts have access to environment variables and secrets
• Platform detection automatically selects the right script variant
• Actions appear as quick-access buttons in the UI

---

Proposed Approaches:

Some ideas that could work. I'd love to get some feedback.

Approach A: Add to UserPreferences (Global Default)

Where to modify:

• shared/src/schemas/settings.ts - Add installScript field to UserPreferencesSchema
• backend/src/services/settings.ts - Settings already handle this schema

Pros:

• Minimal changes - fits existing architecture
• Single global default for all repos
• Works with current settings UI infrastructure

Cons:

• Not per-repo, would need Approach B for overrides
• No platform-specific variants

Schema addition:

installScript: z.string().optional(),

---

Approach B: Add to Repo Schema (Per-Repository)

Where to modify:

• shared/src/schemas/repo.ts - Add installScript field to RepoSchema
• shared/src/types/repo.ts - Add type
• backend/src/db/queries.ts - Handle new field
• backend/src/db/migrations.ts - Add migration for new column

Pros:

• Per-repository configuration
• Fits existing repo management
• Clean separation of concerns

Cons:

• No global default (would need Approach A + C)
• No platform-specific variants

Schema addition:

installScript: z.string().optional(),

---

Approach C: Hybrid - Global + Per-Repo Override

Implementation:

• Combine Approach A (default in UserPreferences) with Approach B (override in Repo)
• Resolution logic: use repo-level if set, otherwise fall back to global

Pros:

• Best UX: sensible defaults with per-repo flexibility
• Matches Codex's hierarchical config (user → project)

Cons:

• Slightly more complex resolution logic
• Need to determine precedence order

---

Approach D: Detect from Repository (Codex-style)

Where to modify:

• Create a new service to scan repo for common config files
• Auto-suggest setup commands based on detected stack:
  • package.json → npm install
  • requirements.txt / pyproject.toml → pip install
  • go.mod → go mod download
  • Cargo.toml → cargo build
  • pom.xml / build.gradle → Maven/Gradle commands

Pros:

• Zero configuration for common cases
• Matches Codex's auto-detection feature

Cons:

• More complex implementation
• May not cover all edge cases
• Need UI for reviewing/editing suggestions