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 validates required dependencies and fails closed when an approved tool is missing. Pre-provision organization-approved, version-pinned tools before running it; the installer does not execute third-party bootstrap scripts.

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. Pre-provision an approved release.
Python 3.10+	Yes	Python 3.12 recommended. Pre-provision an approved release.
Node.js + npm	Yes	Used by dashboard and JavaScript CLIs. Pre-provision an approved release.
Bun	Recommended	Preferred package manager for JavaScript runtime tasks. Pre-provision an approved release.
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

Global JavaScript CLIs are not installed from mutable registries. Provision the approved CodeGraph and other optional CLI artifacts described by your deployment baseline before installation.

Install OSTwin

Recommended

Use the public bootstrapper for normal installs:

Download the bootstrapper to a private temporary file, inspect or verify it, and only then execute it. Do not stream network content into a shell.

installer_file="$(mktemp)"
trap 'rm -f "$installer_file"' EXIT
curl --proto '=https' --tlsv1.2 -fsSL \
  https://twin.igot.ai/installer.sh -o "$installer_file"
chmod 0700 "$installer_file"
export OSTWIN_INSTALLER_VERSION=v1.0.0 # Replace with the approved tag.
bash "$installer_file"

# Non-interactive, after the same verification step
bash "$installer_file" --yes

Controlled deployments should use a specific tagged release and verify its checksum and approved provenance against an independently obtained release manifest before execution. The canonical URL is mutable and is not, by itself, an adequate federal software-supply-chain control.

The bootstrapper downloads only the explicitly selected packaged Go ostwin-installer release and requires its checksum entry. A missing asset, checksum, or SHA-256 implementation fails closed. It never falls back to an unsigned source archive. Release binaries also embed the matching tagged source archive’s SHA-256 digest and refuse to extract different bytes. Custom source URLs require HTTPS plus an explicit --archive-sha256 value. The explicit source-only recovery path requires an immutable commit and an independently obtained SHA-256 digest.

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.