Installation

This guide installs the full OSTwin runtime: CLI, dashboard, agent orchestration scripts, JavaScript tooling, Python environment, OpenCode integration, and optional services.

Prerequisites

The installer can install most missing dependencies for you.

Dependency	Required	Notes
macOS or Linux	Yes	Native Bash installer path.
Bash	Yes	Used by the installer wrapper.
PowerShell 7+	Yes	Used by the orchestration engine. Auto-installed when possible.
Python 3.10+	Yes	Python 3.12 recommended. Auto-installed when possible.
Node.js + npm	Yes	Used by dashboard and JavaScript CLIs. Auto-installed when possible.
Bun	Recommended	Preferred package manager for JavaScript runtime tasks. Auto-installed when possible.
Git	Recommended	Required for room worktree isolation. Shared isolation is the default.
Provider API key	Yes	At least one of Google, OpenAI, Anthropic, or another configured provider.

Tip

The installer also installs global JavaScript CLIs used by OSTwin, including @colbymchenry/codegraph.

Install OSTwin

Recommended

Use the public bootstrapper for normal installs:

curl -fsSL https://twin.igot.ai/installer.sh | bash

# Non-interactive
curl -fsSL https://twin.igot.ai/installer.sh | bash -s -- --yes

The bootstrapper first tries the packaged Go ostwin-installer release. That binary provides the guided terminal flow, downloads the matching source archive, and delegates to the native platform installer.

If the packaged release binary is unavailable, install.sh falls back to the source-archive Bash installer. Checksum mismatches fail closed and do not fall back.

Common forwarded options:

--yes
--dir ~/.ostwin
--port 3366
--skip-optional
--sync-skills
--no-start

Local Clone

Use this path when developing OSTwin or testing installer changes from a checkout:

git clone https://github.com/igot-ai/os-twin.git
cd os-twin
./build.sh --yes

build.sh delegates to .agents/install.sh with local source defaults, so it exercises the current checkout instead of downloading the latest release.

You can also call the native installer directly:

.agents/install.sh --yes

Windows uses the PowerShell native installer:

.agents\install.ps1
.agents\install.ps1 -Yes

Installer Dev

To test the packaged Go installer wrapper from a local checkout:

cd installer
go run ./cmd/ostwin-installer --source-dir .. --dry-run --yes
go run ./cmd/ostwin-installer --source-dir ..
go test ./...

Release packaging is defined in .goreleaser.yml and automated by .github/workflows/installer-release.yml.

Common Installer Options

Option	Purpose
--yes	Run without prompts.
--dir PATH	Install to a custom directory. Default: ~/.ostwin.
--port PORT	Set the dashboard port. Default: 3366.
--skip-optional	Skip optional components.
--sync-skills	Force built-in skill sync.
--no-start	Install only; do not start services.
--dashboard-only	Install dashboard API and frontend only.
--no-channel	Install bot dependencies but do not start channel connectors.

Release Artifacts

Tagged releases publish these installer assets:

install.sh
checksums.txt
ostwin-installer_darwin_amd64.tar.gz
ostwin-installer_darwin_arm64.tar.gz
ostwin-installer_linux_amd64.tar.gz
ostwin-installer_linux_arm64.tar.gz
ostwin-installer_windows_amd64.tar.gz
ostwin-installer_windows_arm64.tar.gz

API Key Setup

OSTwin needs at least one LLM provider key. Add keys to ~/.ostwin/.env after installation:

Anthropic (recommended)

ANTHROPIC_API_KEY=sk-ant-...

OpenAI

OPENAI_API_KEY=sk-...

Google

GOOGLE_API_KEY=AI...

Caution

Never commit API keys to plan files, role configs, or source control.

Reload your shell after installation:

source ~/.zshrc

Use ~/.bashrc instead if your shell is Bash.

Optional Components

Search Engine

Install local SearXNG support during setup:

./build.sh --search-engine --search-engine-mode docker

Or install and start it after setup:

ostwin search-engine install
ostwin search-engine start

The local runner uses ~/.ostwin/.venv/bin/uv, installs SearXNG dependencies from ~/.ostwin/search-engine/searxng-src/requirements.txt, and starts with ~/.ostwin/search-engine/etc/settings.yml.

Dashboard Daemon

Install OS autostart for the dashboard and host daemon:

./build.sh --daemon

Skip daemon setup explicitly:

./build.sh --no-daemon

Channel Connectors

Start Telegram, Discord, and Slack connectors during install:

./build.sh --channel

Skip connector startup:

./build.sh --no-channel

Runtime File Locations

After installation, OSTwin uses this runtime structure:

Path	Purpose
~/.ostwin/.agents/	Installed engine, roles, skills, MCP config, and CLI scripts.
~/.ostwin/.env	Runtime environment variables and provider API keys.
~/.ostwin/plans/	Registered global plans.
<project>/.agents/	Project-local OSTwin scaffold created by ostwin init.
<project>/.war-rooms/	Active war-room directories created at runtime.
<project>/.agents/plans/	Local plan copies that agents can read inside the project sandbox.

Verify Installation

Run the health check:

ostwin health

Check the installed version:

ostwin version

Start or restart the dashboard if it is not already running:

ostwin dashboard start

Open the dashboard at:

http://localhost:3366

Initialize a Project

From the project you want OSTwin to operate on:

ostwin init

Create and run a plan:

ostwin plan create --file plan.md
ostwin run plans/my-feature.md

Monitor execution:

ostwin status --watch
ostwin logs room-001 --follow

By default, OSTwin runs with shared workspace isolation. Use room worktrees only when you need per-room Git worktrees:

ostwin run plans/my-feature.md --workspace-isolation room-worktree

Install and Run the Docs Site

The documentation site lives in docs/ and uses Astro Starlight.

cd docs
npm install --package-lock=false
npm run dev

Build the static docs site:

cd docs
npm run build

Preview the production build:

cd docs
npm run preview

The docs build runs npm run sync-installer first. That copies the root install.sh into docs/public/installer.sh and docs/public/install.sh, keeping the public curl installer URL aligned with the repository installer.

Update an Existing Install

To update an initialized project from the installed framework:

ostwin sync

To refresh the global install from a local checkout:

./build.sh --yes --sync-skills

Uninstall

Remove the local OSTwin install:

~/.ostwin/.agents/uninstall.sh

On Windows:

.agents\uninstall.ps1

Review the uninstall prompt before confirming, especially if you have local plans, logs, or generated artifacts under ~/.ostwin.

Next Steps

With OSTwin installed, create plan.md and start the work in the Quick Start.