Cross-Platform Installation Differences for LifeOS on macOS, Linux, and Windows

LifeOS uses a single unified installer that auto-detects your operating system and adapts the bootstrap tool, background services, and launch workflows accordingly.

LifeOS is an AI-native "operating system" designed to run on any host platform. While the core functionality remains consistent across macOS, Linux, and Windows, the installation process tailors specific components based on OS detection. Understanding these differences ensures smooth deployment regardless of your environment.

Bootstrap Tool Differences by Platform

The first divergence occurs when installing the Bun runtime, which powers LifeOS.

macOS and Linux

Both Unix-like platforms share the same Bash-based installer:

curl -fsSL https://bun.sh/install | bash

Windows

Windows requires PowerShell execution:

powershell -c "irm bun.sh/install.ps1 | iex"

The Windows installer falls back to copy-based file operations where macOS would create symbolic links, and may request elevation for certain permissions.

OS Detection and Environment Reporting

Platform identification happens through DetectEnv in LifeOS/Tools/DetectEnv.ts. This utility runs first and sets the foundation for all subsequent installation steps.

Detected OS	Reported Value	Platform-Specific Behavior
macOS	os: "macOS"	Enables macOS-only components and services
Linux	os: "Linux"	Omits macOS-specific services
Windows	os: "Windows"	Uses PowerShell workflows; skips launchd jobs

The DetectEnv output directly influences which components the Setup workflow in LifeOS/install/skills/LifeOS/Workflows/Setup.md activates.

macOS-Only Background Services

The most significant platform difference involves launchd agents for persistent background operations.

macOS Services (launchd)

On macOS, DeployComponents.ts automatically installs and configures native launchd agents:

• Pulse — core system daemon
• worksweep — workspace management
• derived-sync — synchronization service

Verify active services post-installation:

launchctl list | grep com.lifeos

Linux and Windows Service Gap

Both Linux and Windows installations omit launchd entirely. The DeployComponents.ts script conditionally skips these services when os !== "macOS":

# Deploy only non-launchd components manually (Linux/Windows default behavior)

bun Tools/DeployComponents.ts --components core,optional

This means Linux and Windows users run the core CLI directly without persistent background daemons managed by the OS.

Permission and Security Models

Each platform handles authorization differently during installation.

macOS TCC Requirements

macOS may request TCC (Transparency, Consent, and Control) grants for the native bridge components, particularly the interceptor helper that requires elevated system access.

Linux Permissions

No platform-specific permission framework exists. Standard Unix permissions and user escalation apply.

Windows Elevation

Windows may require administrative elevation for symlink creation. The PowerShell installer handles this transparently.

Complete Installation Workflow

Regardless of platform, the installation follows this unified pattern:

1. Run DetectEnv — bun Tools/DetectEnv.ts
2. Execute setup workflow — follows LifeOS/install/skills/LifeOS/Workflows/Setup.md
3. Install Bun via OS-specific bootstrap (Bash or PowerShell)
4. Scan conflicts and overlay system templates
5. Scaffold user tree with trust-gated hooks
6. Deploy components — launchd services added only on macOS

Launch Command Variations

The final launch command adapts to each platform:

• macOS: Includes system prompt plus launchd-based Pulse daemon references
• Linux: Core CLI invocation (bun …) without launchd flags
• Windows: PowerShell-based execution with adjusted file operations

Key Source Files for Cross-Platform Logic

Understanding these files helps troubleshoot platform-specific issues:

File	Purpose
LifeOS/Tools/DetectEnv.ts	Platform detection and environment reporting
LifeOS/Tools/DeployComponents.ts	Conditional component and service deployment
LifeOS/INSTALL.md	High-level installation guide with OS-specific commands
LifeOS/install/skills/LifeOS/Workflows/Setup.md	Step-by-step adaptive setup workflow
LifeOS/install/skills/LifeOS/INSTALL.md	Detailed platform notes and requirements

Summary

• Bootstrap differs by shell: Bash for macOS/Linux, PowerShell for Windows
• macOS exclusive: Native launchd services for Pulse, worksweep, and derived-sync
• Linux and Windows: Core runtime only; no background service daemons
• Permissions vary: TCC on macOS, standard Unix on Linux, elevation prompts on Windows
• Single codebase: DetectEnv.ts and DeployComponents.ts handle all platform branching

Frequently Asked Questions

Can I run LifeOS background services on Linux or Windows?

No. According to the DeployComponents.ts source code, launchd services are macOS-only and silently skipped on other platforms. Linux and Windows installations provide the core CLI without persistent daemons. You can manually run processes in user space if needed.

How do I verify my platform was detected correctly?

Run bun Tools/DetectEnv.ts and check the os field in the output. Valid values are "macOS", "Linux", or "Windows". This detection drives all subsequent installation decisions in the Setup workflow.

Why does Windows use a different Bun installer?

Windows lacks native Bash support, so the installer uses PowerShell with irm (Invoke-RestMethod) and iex (Invoke-Expression) to download and execute the installation script. The underlying Bun runtime is identical; only the delivery mechanism differs.

Do I need administrator privileges to install LifeOS?

Requirements vary by platform. macOS may need TCC approval for bridge components. Windows may prompt for elevation during symlink creation. Linux typically runs with standard user permissions unless you install system-wide. The PowerShell and Bash installers handle privilege escalation automatically when required.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}