# macOS & Linux One-Liner
curl -fsSL https://raw.githubusercontent.com/richhabits/sam/main/docs/install.sh | bash

# Windows (PowerShell) One-Liner
irm https://raw.githubusercontent.com/richhabits/sam/main/docs/install.ps1 | iex

🌟 The Complete SAM Ecosystem

graph TD
    User([You: Phone, Laptop, or PC])
    
    subgraph Mobile ["📱 SAM Mobile (iOS) — Live on TestFlight · not on the App Store yet"]
        MobileAI[Standalone Direct AI · 30+ Cloud Providers, Zero Setup]
        MobilePair[Optional Desktop Pairing · QR / Local Network]
        MobileYard[Remote Task, Feed & Yard Monitor]
    end
    
    subgraph Core ["💻 SAM Desktop & Server (Mac / Win / Linux)"]
        Agent[Agentic Doer Loop · 257 Tools & 34 Skills]
        Cascade[Cascade Router & 40+ Free Brains]
        Memory[Obsidian-Style Vault & Semantic Cache]
        Overlay[Global ⌥Space Everywhere Overlay]
        Yard[Yard Background Workers & Builds]
        Studio[🎨 SAM Studio · Creative Suite]
        FlipIt[📈 FlipIt Mathematical Risk & Execution Desk]
    end

    User -->|On the Go| MobileAI
    User -->|On Home Wi-Fi / LAN| MobilePair
    MobilePair -->|Sync & Control| Core
    User -->|Direct Computer Use| Core

🚀 Key Superpowers

🧠 1. Cascade Router & 40+ Free AI Brains

• Free-First Auto-Rotation: Groq · Cerebras · NVIDIA NIM · DeepSeek · Gemini · Mistral · SambaNova · Together · Fireworks · Ollama.
• Zero Cost: Automatically falls through to the fastest available free model. If one hits a rate limit, it hops to the next in sub-milliseconds.
• Sub-Millisecond Semantic Cache: Repeated questions answer from local memory in ~2ms with 0 token cost.

🛠️ 2. The Doer (257 Real Computer Tools & 34 Skills)

• Not just text generation. SAM executes terminal commands, edits code with syntax validation, commits to Git, inspects browsers, manages scheduled cron tasks, and orchestrates multi-agent parallel swarms.
• Universal Cross-Platform: 213 universal tools running identically on macOS, Windows, and Linux, with 18 specialized macOS platform hooks that degrade gracefully.

🎨 3. SAM Studio (Creative Suite)

• Free-First Image & Video Generation: Powered by a multi-provider matrix (Pollinations, Together, HuggingFace, NVIDIA, Cloudflare).
• Persistent Media Vault: Automatically stores generated visual assets in your local vault with persistent preview styles.
• Notebooks & Audio Briefings: Upload PDFs, notes, or web links to generate grounded audio overviews and interactive citations.

📈 4. FlipIt & The Financial Execution Desk

• Mathematical Kelly Criterion Engine: Automated capital allocation and real-time risk regime calculation (POST /api/flipit/shield).
• Resilient Watchdogs: Continuous schedule monitoring, forward execution metrics, and market data telemetry.

📱 5. Mobile (iOS) — Live on TestFlight, not on the App Store yet

• 100% Standalone, Zero Setup: Chat immediately on install — no pairing, no account. Routes through 30+ direct cloud AI providers (Groq, Cerebras, Mistral, Gemini, Anthropic, DeepSeek, and more), each addable with your own free key in Settings.
• Optional Desktop Link: Pair with your Mac/PC over local network to unlock local files, automation, and yard workers — never required, only unlocked when you want it.
• Native Feel: Haptics throughout, 1-tap code copy/share, live connection status, and an honest fallback if every AI lane genuinely fails — SAM never fabricates a response.

⚡ Quick Start & Downloads

🖥️ Desktop (macOS / Windows / Linux)

Option A: One-Paste Terminal Install (Recommended)

• macOS (Apple Silicon; Intel uses source until an Intel .dmg ships) & Linux:

  curl -fsSL https://raw.githubusercontent.com/richhabits/sam/main/docs/install.sh | bash
  

• Windows (PowerShell 5.1+ / Windows Terminal):

  irm https://raw.githubusercontent.com/richhabits/sam/main/docs/install.ps1 | iex
  

Option B: Standalone Release Installers

Download the latest binaries directly from the GitHub Releases page:

• macOS: SAM-x.x.x-arm64.dmg (Apple Silicon). Intel .dmg is not in the current release — install.sh refuses to install the arm64 image on Intel; use Option C (from source) until that asset exists.
• Signed vs unsigned: a notarized Developer ID build opens with Gatekeeper accepted (this Mac's 3.6.0 is source=Notarized Developer ID). If Gatekeeper cannot verify, the installer says so and clears quarantine — that is the honest unsigned path, not a silent skip. Overlay (⌥Space) and the Dock icon come from SAM.app, not from the browser HUD.
• Windows: SAM-Setup-x.x.x.exe (v3.6.0: SAM-Setup-3.6.0.exe). One-paste: docs/install.ps1. From source: setup.ps1 + START-SAM.bat (no .sh). The packaged app starts the yard worker; SmartScreen “More info → Run anyway” is the unsigned path.
• Linux (x64): SAM-x.x.x.AppImage (default one-paste → ~/.local/bin/SAM.AppImage) or sam_x.x.x_amd64.deb (SAM_PKG=deb). No arm64 Linux build in the current release — install.sh says so instead of handing you the amd64 image. Needs libfuse2 on some Ubuntu 22+ boxes.

Option C: Run from Source (Developers)

git clone https://github.com/richhabits/sam.git
cd sam
npm install
cp .env.example .env
npm start

Open http://localhost:8787 — free, local, and ready immediately. Opening the HUD on this computer pairs that browser tab (chat, tools, and settings work). A phone or another machine still uses the pairing link SAM prints on start.

📱 Mobile App (iOS)

Status: Live on TestFlight · App Store not live yet (review notes are in mobile/SUBMISSION.md; this session did not press Submit)

• Try it now: Join the TestFlight beta — works immediately, standalone, no desktop required.
• App Store: Not on the store yet. TestFlight is the shipping iOS binary. Widget reads App Group group.com.hectic.sam.mobile (pairing / yard snapshot from the app) — needs a new native build to land on devices.
• Android: Same Expo app as iOS (com.hectic.sam.mobile). Not on Play Store. Debug APK builds: cd mobile/android && ./gradlew assembleDebug → app/build/outputs/apk/debug/app-debug.apk (proved this session, 156MB, minSdk 24). Sideload; demo mode works with no desktop. The platforms badge does not claim Play Store.
• Optional desktop pairing: In the app, tap Connect to Mac / PC (or in SAM Desktop, Dashboard → Devices → Pair a phone) to unlock local files and automation — entirely optional.

📊 SAM vs. The Rest

🔒 Privacy & Local-First Architecture

• All chats, memories, and vault artifacts are stored as plain Markdown & SQLite files in your local workspace (vault/).
• API keys are stored strictly in your local environment / OS Keychain and never sent to external telemetry servers.
• Full offline capability supported with local Ollama models (e.g. llama3.2:3b, qwen2.5-coder).