{"slug": "show-hn-i-made-a-free-and-open-source-muse-instinct", "title": "Show HN: I made a free and open source Muse/Instinct", "summary": "SkyTwin released alpha-0.6.106.0, a free and open-source desktop personal AI assistant that builds a \"digital twin\" model of a user's preferences, risk tolerance, and decision patterns. The unsigned alpha runs on Apple Silicon Macs, x64 Windows, and x86-64 Linux, defaults to local reasoning, and is licensed under Apache-2.0, with Gmail inbox connection available through a user-supplied Google OAuth client. The project positions the assistant's policy model to check trust, spend, risk, reversibility, and origin before acting, leaving authority decisions to the user.", "body_md": "**Open-source personal AI. A digital twin that learns what matters to you, with you in control.**\n\nImagine opening your day to a short list of what needs you, with the context already there: what happened, why it matters, and what your AI thinks you would want to do. Correct it once, and see what it learned.\n\nThat's the experience SkyTwin is building. Your **digital twin** is a growing model of your preferences, risk tolerance, and decision patterns. The goal is fewer repeated explanations and less routine decision work, with a visible reason behind each suggestion and clear limits on what it may do for you.\n\nIf personal AI already appeals to you, SkyTwin gives you a way to explore the next question: how should an assistant learn your judgment, earn permission to act, and stay accountable as it improves? You can inspect its memory, correct its assumptions, choose where reasoning runs, and adapt the source.\n\n[Download the current desktop alpha](https://github.com/jayzalowitz/skytwin/releases/tag/alpha-0.6.106.0) · [Explore SkyTwin](https://jayzalowitz.github.io/skytwin/) · [Take the five-minute tour](https://jayzalowitz.github.io/skytwin/how-to-use.html) · [Run the latest source](https://jayzalowitz.github.io/skytwin/start.html#source)\n\n**Try it today:** the current unsigned desktop alpha is a real packaged app for Apple Silicon Macs, x64 Windows, and x86-64 Linux—no source checkout required. On first launch, create an account by supplying a Google Web Application OAuth client that you create and control; the desktop window runs the local dashboard and walks you through the consent flow. After the first account is established, an authenticated browser can use the same dashboard at `http://localhost:3200`. A fictional-data sample remains available when you do not want to connect an inbox. This is an alpha release: expect OS warnings, and do not interpret it as a managed OAuth service, Google verification, signing, or notarization claim.\n\n*Actual app screenshot from a source development run, using fictional sample data. The messages, account indicators, and “handled” counts illustrate the product; no real account is connected and no real task was executed.*\n\nThe core principle is **ask the twin before asking the user**. The intended experience brings a few things together:\n\n- **Know what needs you.** A briefing separates things to act on from things to catch up on, with the source behind each item.\n- **Stop repeating yourself.** Preferences have supporting evidence, confidence, and a history you can inspect. You can see what the twin believes and correct it.\n- **Understand the suggestion.** Review what happened, which preferences mattered, why an action was proposed, and how to change its mind.\n- **Give it room at your pace.** The policy model starts with suggestions and checks trust, spend, risk, reversibility, and origin before considering an action. You decide what authority to grant.\n- **Keep your choices yours.** Local reasoning is the default and does not silently fall back to a remote provider. Hosted reasoning is an explicit choice. The code is Apache-2.0 licensed.\n\nThe current desktop alpha lets you connect a real Gmail inbox through your own Google OAuth app. Use its desktop window for first-account setup; the same local web dashboard can be used in a browser that already holds a valid SkyTwin session. The fictional sample lets you experience the review-and-correct loop without connecting an account. The Gmail path is an advanced alpha capability—not a supported managed SkyTwin OAuth service or a claim of current Google verification.\n\nFor the fastest real-app path, [download the current desktop alpha](https://github.com/jayzalowitz/skytwin/releases/tag/alpha-0.6.106.0). Start with the [screenshot-led walkthrough](https://jayzalowitz.github.io/skytwin/how-to-use.html), or follow the [source start guide](https://jayzalowitz.github.io/skytwin/start.html#source) to explore the fictional sample yourself. You do not need an inbox, credentials, or an AI provider key for the sample.\n\n1. **Meet the sample twin.** Open the fictional profile's briefing and see what\nneeds a decision, alongside what is just useful to know.\n2. **Follow a suggestion.** Inspect a decision, the evidence behind it, and the\nexplanation of why it needs approval.\n3. **Try a correction.** Use the sample's simulated approve, reject, or correct\ncontrols and see the session-local learning. The product views are read-only;\nthese interactions have no provider, connector, or execution-adapter effects.\n4. **Explore what it remembers.** Visit “What I've learned” to see the preferences\nbehind the suggestions. Think about which of your own routines you would want\na twin to learn.\n\nFor a plain-language walkthrough, begin with [how to use the fictional sample](https://jayzalowitz.github.io/skytwin/how-to-use.html), then use the [documentation site](https://jayzalowitz.github.io/skytwin/docs.html):\n[how to start](https://jayzalowitz.github.io/skytwin/start.html),\n[how safety works](https://jayzalowitz.github.io/skytwin/safety.html),\n[where inference runs](https://jayzalowitz.github.io/skytwin/inference.html),\nand the [five-minute fictional-data demo](https://jayzalowitz.github.io/skytwin/demo.html).\n\nThese examples explain the intended judgment model; they are not a list of workflows included in the current desktop artifacts. The beta release contract below limits launch support to workflows backed by tagged-artifact evidence.\n\n| Future scenario | Intended experience | \n|---|---|\n| **Newsletter arrives** | Your twin recognizes your archive pattern and proposes moving the message out of the Inbox. You confirm before the mailbox changes, and the explanation is logged. | \n| **Calendar conflict** | You always prioritize skip-level 1:1s over standups. Standup rescheduled with a note to the organizer. | \n| **Subscription renewal** | $15.99/mo streaming service, used 3x this month, 18 months of renewals. Auto-renewed within your spend norms. | \n| **Grocery reorder** | Repeats your last order with your substitution rules. Flags the one item that jumped 15% in price. | \n| **Flight booking** | Finds the United aisle seat, morning departure, direct, $380. At high trust: books it. At low trust: presents top 3 options. | \n| **Unknown sender email** | Low confidence. Escalates with a one-line summary so you can decide in 5 seconds instead of 5 minutes. | \n\n**Conversation connects to decisions.** SkyTwin includes chat and an “Ask your twin” surface. Its broader goal is to bring the same personal context into briefings, suggestions, and eventually connected-account actions, so useful work can begin without a new prompt each time.\n\n**Trust grows domain by domain.** New users start at `observer` — the system only suggests. Its trust model lets approvals and corrections inform autonomy separately for each domain; trust in email triage need not imply trust with your calendar. See the [policy types](https://github.com/jayzalowitz/skytwin/blob/main/packages/shared-types/src/policy.ts) and [policy engine](https://github.com/jayzalowitz/skytwin/blob/main/packages/policy-engine/src).\n\n**Safety constraints are the product.** Typed candidate-action paths through the policy engine apply spend limits, trust-tier gating, reversibility checks, and sensitivity classification; the release-wide entry-path inventory remains a beta gate. The system can be inspected, overridden, narrowed, and shut off at any time. [Read the full safety model →](https://github.com/jayzalowitz/skytwin/blob/main/docs/safety-model.md)\n\n**Recorded decisions are inspectable.** Supported paths can produce an explanation record covering what happened, the evidence and preferences used, the selected action, and correction guidance. Release-wide explanation coverage is still under audit, and a hosted model's internal reasoning remains subject to that provider's own transparency limits.\n\n**Your twin is inspectable.** It's not a vector embedding or a bag of keywords. It's a typed, versioned data structure where every preference has a confidence level, supporting evidence, and provenance. Contradictions are tracked, not hidden.\n\n**Memory knows who said what.** Signals from supported connectors arrive stamped with an authoring tier — content you wrote vs. a newsletter vs. an inbound stranger — and tier-weighted retrieval lets self-authored content outrank broadcast noise. The twin feels like it knows *you* instead of just having read your inbox.\n\n**You can teach a Watch.** The source includes versioned, read-only signal-digest workflows: describe what to watch for, replay a candidate, compare revisions, and explicitly activate or roll back a version. These are a separate development surface, outside the disposable sample credential. Model-assisted authoring requires a qualified model, artifact, and runtime build; the current catalog's downloadable model has not cleared that quality gate. [Explore Watches →](https://jayzalowitz.github.io/skytwin/workflows.html)\n\n| If you want to… | Start here | Then go deeper | \n|---|---|---|\n| Try the packaged desktop app now | [Download the alpha](https://github.com/jayzalowitz/skytwin/releases/tag/alpha-0.6.106.0) | [Alpha limitations and OS warning steps](https://jayzalowitz.github.io/skytwin/start.html#alpha) | \n| Connect a real Gmail inbox from the app (or an authenticated local web session) | [Gmail setup guide](https://jayzalowitz.github.io/skytwin/connect-gmail.html) | [Privacy boundary](https://jayzalowitz.github.io/skytwin/privacy.html) and[Google API plan](https://github.com/jayzalowitz/skytwin/blob/main/docs/google-verification.md) | \n| Understand the idea without installing anything | [Documentation site](https://jayzalowitz.github.io/skytwin/) | [Plain-language FAQ](https://jayzalowitz.github.io/skytwin/faq.html) and[glossary](https://jayzalowitz.github.io/skytwin/glossary.html) | \n| See the product model safely | [Five-minute fictional-data walkthrough](https://jayzalowitz.github.io/skytwin/how-to-use.html) | [Safety model](https://jayzalowitz.github.io/skytwin/safety.html) and[data guide](https://jayzalowitz.github.io/skytwin/data.html) | \n| Run and inspect the source | [Source start guide](https://jayzalowitz.github.io/skytwin/start.html) | [Operations guide](https://jayzalowitz.github.io/skytwin/operations.html) and[troubleshooting](https://jayzalowitz.github.io/skytwin/troubleshooting.html) | \n| Extend it with tools or agents | [Agent and MCP guide](https://jayzalowitz.github.io/skytwin/agents.html) | [Architecture](https://jayzalowitz.github.io/skytwin/architecture.html) and[reference](https://jayzalowitz.github.io/skytwin/reference.html) | \n\nThe rest of this README covers installation, source architecture, deployment, and release status. The [full documentation index](#documentation) keeps every technical guide within reach.\n\n[Open the SkyTwin desktop alpha release →](https://github.com/jayzalowitz/skytwin/releases/tag/alpha-0.6.106.0)\n\nDownload the installer for Apple Silicon macOS, x64 Windows, or x86-64 Linux and open the packaged app. No repository checkout is required. This is the quickest way to try SkyTwin as an application rather than only reading the tour or running the fictional source sample.\n\nThe alpha is unsigned. macOS Gatekeeper and Windows SmartScreen will warn on\nfirst launch; follow the [platform-specific steps below](#downloadable-desktop-alpha).\nIt packages current `0.6.106.0` source under the prerelease tag\n`alpha-0.6.106.0`. It is not the planned supported `v0.7.0-beta` and does not carry\nsigning,\nnotarization, auto-update, or clean-machine evidence.\n\nThe same current alpha can connect a real Gmail inbox or open the account-free\nsample. Keep the app running and open **Connect Gmail** in its desktop\nwindow for the reliable first-account flow. The same page is served at\n`http://localhost:3200/#/connect-gmail`, but a fresh browser does not inherit the\ndesktop's session token; use that browser route only after the browser has been\npaired or otherwise authenticated. Create a Web Application OAuth client in a Google\nCloud project you control, add SkyTwin's loopback callback URLs, then paste the\nclient ID and secret into the wizard. SkyTwin requests Google identity,\nCalendar, `gmail.readonly`, and\n`gmail.modify` scopes and its worker uses the resulting grant to ingest live\nsignals. Use a test account first: the OAuth client secret and newly authorized\ntokens are stored without app-level encryption in the alpha's configured\ndatabase, the build is unsigned, and supported Gmail/Calendar mutation is not\npart of the capability claim. Follow the [real-inbox setup guide](https://jayzalowitz.github.io/skytwin/connect-gmail.html).\n\n```\ncurl -fsSL https://raw.githubusercontent.com/jayzalowitz/skytwin/main/install.sh | bash\n```\n\nThe installer detects your OS, installs anything missing (Homebrew on mac, Node 20+, pnpm), fetches the official CockroachDB single-node binary (hash-verified), clones the repo to `~/skytwin`, runs the bootstrap, starts the services, and opens the dashboard at `http://localhost:3200` once it's up. Re-running pulls latest and restarts.\n\nThe command above intentionally follows the moving `main` branch. For a\nreviewable, immutable source evaluation, use the exact-commit archive workflow\nin [Internal Source Candidates](https://github.com/jayzalowitz/skytwin/blob/main/docs/internal-source-candidates.md). Those\narchives are source-only internal materials, not public releases, and preserve\nthe existing signed-artifact beta gate.\n\n**No Docker required.** Before v0.6.56 the installer pulled Docker Desktop and ran CockroachDB inside a container — by far the heaviest dependency on the list, with its own EULA and a \"open it once after install\" gotcha. The default path now installs the CRDB binary directly into `~/.local/share/skytwin/bin/cockroach` and spawns it as a child process. Docker remains supported via `SKYTWIN_USE_DOCKER=true` for users who already have a Docker workflow.\n\nTo stop later: `cd ~/skytwin && ./bin/skytwin-dev --stop`.\n\n**The first 60 seconds in a development/source run:**\n\n1. The dashboard opens. \"Ask your twin\" can show a predicted action, confidence, alternatives, and an explanation; the exact model-backed path depends on an available local runtime or provider, while deterministic fallbacks cover supported paths when no model responds.\n2. After `pnpm db:seed` , click**\"Just show me around\"** on the welcome screen to skip OAuth and use the development demo seed. Alex has recent decisions, a daily briefing, four pending approvals, \"What I've learned\", Capabilities, Search, and a trust bar climbing toward \"handle most things\". The development seed also includes Pat (a power user) and Carol (a brand-new user), so the dev \"Switch user\" button tells three stories. This development path can exercise mock approval actions; it is separate from the packaged build's read-only data authority and isolated, non-persistent simulation.\n3. The welcome screen recommends a local model from the machine's RAM, architecture, and free disk. The current maintained catalog contains one pinned Qwen2.5 1.5B Instruct Q4_K_M artifact (about 1.0 GiB). The artifact is downloaded on request and must pass exact-size, SHA-256, registry, and runtime-compatibility checks before automatic discovery will load it. A compatible llama.cpp binary remains a separate prerequisite. The artifact remains available for ordinary local inference but is not qualified for adaptive-workflow authoring because it did not clear the checked-in quality gate. \"Change\" opens Settings → AI (and the local memory backend).\n4. Want to look around first? Press **Esc** , click the**×** in the modal corner, or hit**Skip for now** — the dashboard chrome stays navigable behind the modal, and a \"Sign in\" button on the placeholder gets you back into the wizard whenever you're ready.\n5. The packaged alpha offers both its isolated sample and the installation-bound\nBYO Google wizard. Advanced source operators can explicitly enable the same\nprovider path with `SKYTWIN_GOOGLE_CONNECTION_MODE=experimental` . Neither path is a managed or\nsupported public OAuth service.\n\nThe default source install starts SkyTwin's core services without Docker or a hosted-model API key. Model-backed reasoning still requires an available local runtime plus verified model artifact, or a provider you configure. Power users can opt into:\n\n| Env var | Effect | \n|---|---|\n| `SKYTWIN_USE_DOCKER=true` | Run CockroachDB inside Docker instead of as a native binary. Useful for users who already have Docker and prefer container lifecycle. | \n| `SKYTWIN_DOCKER_SQL_PORT` ,`SKYTWIN_DOCKER_ADMIN_PORT` ,`SKYTWIN_DOCKER_API_PORT` | Override Docker Compose host ports for SQL, the Cockroach admin UI, and the optional API container. Useful when another Conductor workspace or local stack already owns `26257` ,`8080` , or`3000` . | \n| `TURBO_DEV_CONCURRENCY` | Override the `pnpm dev` Turbo concurrency. The default is`50` , high enough for the current persistent dev task count. | \n| `SKYTWIN_DEV_SKIP_PORT_PREFLIGHT=1` | Bypass the `pnpm dev` port preflight. Use only when you intentionally want Turbo to try starting even though a required dev port is already listening. | \n| `SKYTWIN_WITH_OLLAMA=true` | Install Ollama + pull the gemma4 model (~9.6GB). Without this opt-in, local inference requires a separately installed `llama.cpp` binary and compatible model. | \n| `SKYTWIN_DISABLE_EMBEDDED=1` | Skip the embedded LLM provider in the API's provider chain. Pair with hosted-only keys (e.g. `ANTHROPIC_API_KEY` ) for reproducible evaluation runs. | \n| `SKYTWIN_LLAMA_MODEL=/path/model.gguf` | Opt into a user-managed model path. This explicit override bypasses the managed-model manifest and registry checks; the user is responsible for the artifact's provenance and compatibility. | \n| `SKYTWIN_REASONING_MODE` | Pin the environment-driven chain to `on_device` or`bring_your_own_provider` . Mixed local/remote chains require this explicit choice. Verified private cloud is configured per user in Settings so its key and isolated provider snapshot are explicit. | \n| `SKYTWIN_CRDB_VERSION` | Pin a non-default CockroachDB version. Refresh the hash tables in `bin/skytwin-db` and`apps/desktop/scripts/build-single-binary.sh` together. | \n\nOn-device Ollama requires Ollama 0.18 or newer. SkyTwin adds Ollama's\nrequest-scoped `:local` source selector to every on-device call and never\nretries the unqualified model name; this prevents a loopback daemon from\nrelaying a remote-backed model alias. General local chat is supported, but\nreleased Ollama builds do not attest the exact served digest/runtime on each\nchat response, so adaptive workflow authoring and summaries currently fail\nclosed. For defense in depth, disable Ollama Cloud globally with\n`OLLAMA_NO_CLOUD=1` or `disable_ollama_cloud: true`.\n\nIf you'd rather drive each step yourself:\n\n**Prerequisites**\n\n- [Node.js](https://nodejs.org/) >= 20\n- [pnpm](https://pnpm.io/) >= 9\n- That's it. CockroachDB is fetched as a native binary by `bin/skytwin-db install` . No Docker, no system DB install.\n\n```\ngit clone https://github.com/jayzalowitz/skytwin.git && cd skytwin\npnpm install\n\n# Fetch + start CockroachDB (native binary, hash-verified)\n./bin/skytwin-db install\n./bin/skytwin-db start\n./bin/skytwin-db ensure-db\n\n# Configure\ncp .env.example .env   # edit with your values\n\n# Migrate and seed\npnpm db:migrate\npnpm db:seed\n\n# Build and run\npnpm build\npnpm dev\n```\n\nThe API starts on `localhost:3100`, the web dashboard on `localhost:3200`.\n`pnpm dev` preflights the API, web, OpenClaw bridge, and Twin MCP ports before\nTurbo starts. If another process owns a required port, it prints the owning\nPID/command/cwd; if this same workspace is already healthy, it exits cleanly\ninstead of starting a duplicate dev stack.\nThe OpenClaw bridge is supervised during `pnpm dev`, so a one-off child\nSIGKILL/exit 137 restarts the bridge without tearing down API/web/worker; fast\ncrash loops still fail visibly.\n\nBefore shipping, regression-check the install end-to-end across a matrix of Linux distros:\n\n```\n./bin/validate-installs              # Ubuntu 22.04, Debian 12, Fedora 40\n./bin/validate-installs ubuntu       # one distro\n./bin/validate-installs --keep-on-fail ubuntu  # leave container alive on failure\n```\n\nEach run spawns a fresh OS container, untars a snapshot of the working\ntree, runs `install.sh` exactly the way a real user would, and asserts\nthe dashboard responds at `localhost:3200`. macOS/Windows are exercised\nvia the same `install.sh` and `bin/skytwin-db` codepaths but need a real\nmachine to verify the platform-specific bits (Homebrew, NSIS, etc.).\n\n```\npnpm test   # 4,800+ tests across 400+ files in 31 packages + 8 apps\n```\n\n[View the desktop alpha release →](https://github.com/jayzalowitz/skytwin/releases/tag/alpha-0.6.106.0)\n\nThe published alpha artifacts are a usable packaged application, not just the\nfictional demo. They bundle the desktop stack described by their release notes,\nincluding CockroachDB, but they are unsigned and are not supported public-beta\ninstallers. The tagged release path can generate and attach updater manifests,\nbut no qualifying beta release is currently published; do not infer manifest\npresence or update support from the current preview. Check the release notes for\nthe exact features in an artifact. In\nbuilds from current source, a local model and the `llama.cpp` runtime are not\nbundled: SkyTwin can recommend a maintained artifact for the machine and download\nit only after the user starts the install. A compatible runtime remains a separate\nprerequisite, while a hosted provider remains an explicit opt-in.\n\nThe alpha also includes a real-inbox mode. Keep it running and use\n**Connect Gmail** inside the desktop window for first-account setup. The same\npage is available at `http://localhost:3200/#/connect-gmail` to a browser that\nalready has a valid SkyTwin session; opening it in a fresh browser does not copy\nthe desktop session. The wizard walks you through creating a\npersonal Google Cloud OAuth client and grants the worker access to ingest your\nGmail and Calendar data. This is the quickest way to try SkyTwin with an actual\ninbox, but it carries the alpha's older plaintext credential/token custody and\nunsigned-build limitations. Use a test Google account first and see the\n[step-by-step Gmail guide](https://jayzalowitz.github.io/skytwin/connect-gmail.html).\n\n**Release boundary:** the current unsigned alpha packages the guarded,\naccount-free sample session but does not claim verified managed-model delivery\nor beta evidence. Check the release notes for the exact features in an artifact.\nThe desktop can open a short-lived sample whose database-backed surface remains read-only;\napprove, reject, correct, and learn interactions run only in a separate,\nsession-local simulation that cannot reach providers or execution adapters.\nIts browser credential is tab-scoped and [bypasses offline caching and replay](https://github.com/jayzalowitz/skytwin/blob/main/apps/web/public/js/pwa/sw-policy.js).\n\n| OS | Direct alpha download | \n|---|---|\n| **macOS** (Apple Silicon) | [Open the current release assets](https://github.com/jayzalowitz/skytwin/releases/tag/alpha-0.6.106.0) | \n| **Windows** | [Open the current release assets](https://github.com/jayzalowitz/skytwin/releases/tag/alpha-0.6.106.0) | \n| **Linux** | [Open the current AppImage, `.deb`, and `.rpm` assets](https://github.com/jayzalowitz/skytwin/releases/tag/alpha-0.6.106.0) | \n\n**⚠ Unsigned builds (for now).** Code-signing certs (Apple Developer + Windows EV) are a pending launch step, so your OS warns on first launch:\n\n**macOS:** right-click the app → **Open** → **Open** (clears Gatekeeper once).\n**Windows:** SmartScreen → **More info** → **Run anyway**.\nSigning and notarization are stop-ship requirements for a supported public beta.\n\nThis is the source architecture and connected-account pipeline. The guarded current-source preview feeds it isolated fictional sample data by default. The current desktop alpha can instead ingest a real Gmail inbox through a self-created Google OAuth client, and source operators can enable the retained path explicitly in experimental mode.\n\n```\n  Gmail, Calendar, etc.\n         │\n         ▼\n  ┌──────────────┐\n  │   Connectors  │  Ingest signals from your accounts\n  └──────┬───────┘\n         ▼\n  ┌──────────────┐\n  │   Decision    │  \"What's happening? What would\n  │   Engine      │   the user want here?\"\n  └──────┬───────┘\n         ▼\n  ┌──────────────┐\n  │  Twin Model   │  Your preferences, patterns,\n  │  + Memory     │  and episodic memory (gbrain default,\n  │               │  MemPalace optional)\n  └──────┬───────┘\n         ▼\n  ┌──────────────┐\n  │   Policy      │  Spend limits, trust tiers,\n  │   Engine      │  safety constraints\n  └──────┬───────┘\n         ▼\n    ┌────┴────┐\n    ▼         ▼\n Auto-     Escalate\n execute   with context\n    │         │\n    ▼         ▼\n Explain   You decide\n    │         │\n    └────┬────┘\n         ▼\n  ┌──────────────┐\n  │  Feedback     │  Your response trains the twin\n  │  Loop         │  to be better next time\n  └──────────────┘\n```\n\nSupported decision paths can persist explanation and feedback records. Release-wide coverage is still being audited before the public beta.\n\nSkyTwin is a TypeScript monorepo (pnpm + Turborepo) with 31 packages and 8 apps:\n\n```\napps/\n  api/                HTTP API — decisions, user management, webhooks, /api/voice/*\n  web/                Dashboard — review decisions, manage preferences, configure policies\n  worker/             Background jobs — async execution, briefing generation, memory action loop, tier backfill\n  idle-miner-runner/  Desktop-managed child that scans approved project roots only while the machine is idle\n  desktop/            Electron app — macOS (.dmg), Windows (.exe), Linux (.AppImage)\n  mobile/             React Native (Expo) — QR pairing, push notifications, SSE, voice capture\n  openclaw-bridge/    OpenClaw proxy — bridges local API to OpenClaw execution service\n  twin-mcp-server/    MCP server exposing the twin's read-only surface to external clients\n\npackages/\n  shared-types/                   TypeScript interfaces — the dependency root for everything\n  config/                         Env var loading and validation\n  core/                           Retry logic, circuit breaker, error types, logging\n  db/                             CockroachDB client, migrations, repositories\n  twin-model/                     Twin profile CRUD, preference learning, confidence scoring\n  decision-engine/                Event interpretation, candidate generation, action selection\n  policy-engine/                  Trust tiers, spend limits, domain policies, safety checks\n  policy-prompts/                 Versioned LLM prompts with JSON schema validation and deterministic fallbacks\n  ironclaw-adapter/               Execution adapter with HMAC auth, retries, circuit breaker\n  execution-router/               Adapter selection, fallback chains, risk modifiers, plugin discovery\n  llm-client/                     Unified LLM client — local, conventional, and admitted TrustedRouter paths; NEAR represented but blocked\n  near-confidential/              Fail-closed NEAR verification contract; no transport is runtime-admitted\n  embedded-llm/                   Local-first: llama.cpp text, whisper.cpp STT, Piper TTS — spawn-based\n  explanations/                   Human-readable explanation generation\n  connectors/                     Gmail / Google Calendar / Outlook mail+calendar / mock connectors; real accounts are opt-in alpha/experimental paths\n  assistant/                      Stateless chat service wrapping LlmClient with context enrichment\n  capability-engine/              Infers user app capabilities from signals (keyword v1 + LLM verification)\n  credential-vault/               AES-256-GCM + scrypt primitives for the experimental token vault (not production-default encryption)\n  idle-miner/                     Filesystem scanner that extracts project metadata during idle time\n  mcp-host/                       Manages MCP servers (stdio/HTTP/SSE) with circuit breakers + telemetry\n  dxt/                            Serializes/deserializes DXT artifacts (packed MCP server configs)\n  observability/                  In-memory metrics + ring-buffered rollup for the capability loop\n  registry-client/                Loads curated MCP registry entries with OAuth quirks and service lookup\n  routines/                       Typed read-only Watch providers: canonical payloads, compilation, replay, semantic diff, and run evidence\n  mempalace/                      Legacy memory: episodic, knowledge graph, 4-layer retrieval (opt-in backend)\n  memory-port/                    Backend-agnostic MemoryPort interface + capability negotiation\n  memory-gbrain/                  Default gbrain-compatible backend on CRDB; upstream CLI interoperability adapter (never runtime-selected)\n  memory-gbrain-crdb-adapter/     CRDB driver for gbrain — tier-weighted RRF, pin/hide, embedding providers\n  memory-hybrid/                  Composes any two MemoryPort impls — per-capability read routing\n  memory-mempalace/               MemoryPort adapter for the legacy mempalace classes\n  evals/                          Decision quality evaluation and regression testing\n```\n\n| Layer | Technology | \n|---|---|\n| Language | TypeScript (strict, ES2022) | \n| Database | CockroachDB (PostgreSQL wire protocol) | \n| Runtime | Node.js >= 20 | \n| Package Manager | pnpm with workspaces | \n| Build | Turborepo | \n| Desktop | Electron + electron-builder | \n| Mobile | React Native + Expo | \n| Testing | Vitest (4,800+ tests) | \n| CI/CD | GitHub Actions | \n| Execution | [IronClaw](https://github.com/nearai/ironclaw/) , OpenClaw (via local bridge), and Direct execution — trust-ranked selection with ambiguous attempts held for reconciliation | \n\nThe API uses `req.ip` for every IP-keyed check: the session-auth\nlocalhost dev-bypass, the OAuth new-user rate limit, the\n`/api/v1/demo/preview` per-IP bucket, and any future per-client limit.\nBehind any reverse proxy, `req.ip` is the proxy's address by default —\nwhich collapses every per-IP limit into a single shared bucket. You\nneed `TRUST_PROXY_HOPS` set to the exact number of trusted hops between\nthe Node process and the real client.\n\nThe number you want is \"trusted proxies between this Node process and the\nactual client\" — count every box that legitimately appends to\n`X-Forwarded-For` on its way in, including any platform-injected router\nyour provider sits behind.\n\n| Topology | `TRUST_PROXY_HOPS` | \n|---|---|\n| Direct (no proxy, or untrusted upstream) | `0` (default) | \n| Single reverse proxy (your own nginx, Caddy, ELB target) | `1` | \n| Single platform hop (Fly's edge, Render's router, Heroku's app router, an AWS ALB on its own) | `1` | \n| CDN → your reverse proxy (Cloudflare → nginx → Node, no platform router) | `2` | \n| CDN → platform router → Node (Cloudflare → Fly/Render/Heroku → Node) | `2` | \n| CDN → platform router → your reverse proxy → Node (Cloudflare → Fly → nginx → Node) | `3` | \n| Multi-hop edge (Cloudflare → AWS WAF → ALB → Node) | `3+` | \n\nIf you can't draw the topology from memory, prefer Express's array/CIDR\nform for `trust proxy` (set per-network, not per-hop) — see the\n[Express docs](https://expressjs.com/en/guide/behind-proxies.html). Hop\ncounts are simple but brittle when a platform inserts a hop you didn't\nknow about.\n\n**Setting this too high is a security hole.** A client-controlled\n`X-Forwarded-For` becomes `req.ip` and bypasses every per-IP limit by\nheader rotation. **When in doubt, prefer fewer hops.**\n\nVerify after deploy:\n\n```\ncurl -H 'X-Forwarded-For: 1.2.3.4' https://your-api/api/health/live\n# response includes {\"clientIp\": \"...\"} — should NOT be \"1.2.3.4\"\n# unless 1.2.3.4 is actually a trusted upstream\n```\n\nIf `clientIp` in the response matches the spoofed header, your\n`TRUST_PROXY_HOPS` is too permissive and rate-limit bypass is open.\n\nThe public LLM-backed preview endpoint has three layers of protection:\n\n| Env var | Default | Purpose | \n|---|---|---|\n| `DEMO_PREVIEW_DISABLED` | unset | Set to `1` to return 503 unconditionally — operator kill switch when the endpoint gets abused. | \n| `DEMO_PREVIEW_GLOBAL_LIMIT_PER_HOUR` | `500` | Hard global cap across all callers. Survives misconfigured `TRUST_PROXY_HOPS` and rotated-IP abuse. | \n| Per-IP bucket | 20 / 5 min | Built in. Effectiveness depends on `TRUST_PROXY_HOPS` resolving the real client IP. | \n\nThe per-IP bucket and the global cap are process-local. If you run multiple API replicas, the global cap multiplies by replica count. For unauthenticated public deployments at scale, replace the in-memory counter with Redis or a DB row with atomic increment (tracked in TODOS.md as a P3).\n\nSkyTwin uses a progressive trust model. Autonomy is earned, not assumed.\n\n| Tier | What It Means | \n|---|---|\n| `observer` | Default for new users. The twin proposes actions and surfaces them as approval requests — you approve, reject, or edit. Never auto-executes. | \n| `suggest` | Drafts actions for your review. You approve or edit before anything happens. | \n| `low_autonomy` | Auto-executes low-risk, reversible actions in trusted domains. Escalates everything else. | \n| `moderate_autonomy` | Handles most routine decisions. Escalates novel situations and high-cost actions. | \n| `high_autonomy` | Acts on your behalf across domains. Still respects hard limits and irreversibility checks. | \n\nTrust is **domain-specific**. You might be at `moderate_autonomy` for email but `suggest` for calendar. A bad decision in one domain can reduce trust in that domain without affecting others.\n\n| Document | What's Inside | \n|---|---|\n| [How to Use the Fictional Sample](https://jayzalowitz.github.io/skytwin/how-to-use.html) | A plain-language, screenshot-led tour of the current source development sample. It identifies its fictional data and distinguishes it from published technical-preview installers. | \n| [FAQ and Glossary](https://jayzalowitz.github.io/skytwin/faq.html) | Direct answers and defined terms for preview status, safety, privacy, inference, agents, and the release boundary. | \n| [Data and Memory Guide](https://jayzalowitz.github.io/skytwin/data.html) | Current storage disclosure, credential separation, backup/restore semantics, memory backends, and control boundaries. | \n| [Integration Status](https://jayzalowitz.github.io/skytwin/integrations.html) | What is available in the fictional sample, how local MCP and admitted execution differ, and which connector or DXT surfaces remain unavailable or forward-looking. | \n| [Troubleshooting](https://jayzalowitz.github.io/skytwin/troubleshooting.html) | Source-run baseline checks, migrations, seeding, local build recovery, ports, and safe issue-reporting guidance. | \n| [Documentation Site](https://jayzalowitz.github.io/skytwin/docs.html) | Human evaluation guides plus architecture, safety, inference/privacy, MCP-agent, operations, release-evidence, and contribution references. The Pages site is source-first; GitHub remains canonical for implementation details. | \n| [Versioned Workflows](https://jayzalowitz.github.io/skytwin/workflows.html) | Public guide to teaching, replaying, explicitly activating, immutably revising, and rolling back the current read-only signal-digest workflow; the full source contract remains in [Adaptive Workflows](https://github.com/jayzalowitz/skytwin/blob/main/docs/adaptive-workflows.md) . | \n| [The Deck](https://jayzalowitz.github.io/skytwin/deck.html) | 22 slides: every capability claim paired with the mechanism that constrains it. Each claim-and-gate slide carries a collapsible source block citing the file and lines it came from; the \"why now\" and positioning slides cite external sources instead, and three narrative slides carry no citation block ( [source](https://github.com/jayzalowitz/skytwin/blob/main/docs/deck.html) ) | \n| [Product Spec](https://github.com/jayzalowitz/skytwin/blob/main/docs/product-spec.md) | Vision, target user, operating principles, example workflows | \n| [Adaptive Workflows](https://github.com/jayzalowitz/skytwin/blob/main/docs/adaptive-workflows.md) | Canonical source contract for immutable signal-digest workflows, model qualification, exact run evidence, backup/restore, and CockroachDB invariants | \n| [Technical Spec](https://github.com/jayzalowitz/skytwin/blob/main/docs/technical-spec.md) | Architecture, data flow, API endpoints, database schema | \n| [Safety Model](https://github.com/jayzalowitz/skytwin/blob/main/docs/safety-model.md) | Threat model, trust tiers, defense layers, safety philosophy | \n| [Inference Receipts](https://github.com/jayzalowitz/skytwin/blob/main/docs/inference-receipts.md) | Versioned receipt contract, decision-event capture, developer verifier, trust boundary, and current UI/export limitations | \n| [Confidential Inference](https://github.com/jayzalowitz/skytwin/blob/main/docs/confidential-inference.md) | Local-first admission, fail-closed TrustedRouter, and why NEAR AI remains verification-pending | \n| [Decision Engine](https://github.com/jayzalowitz/skytwin/blob/main/docs/decision-engine.md) | Situation interpretation, risk assessment, confidence scoring | \n| [IronClaw Integration](https://github.com/jayzalowitz/skytwin/blob/main/docs/ironclaw-integration.md) | Execution adapter, HMAC auth, failure handling | \n| [CockroachDB Architecture](https://github.com/jayzalowitz/skytwin/blob/main/docs/cockroach-architecture.md) | Schema design, query patterns, versioning, receipt and effect boundaries | \n| [Evals](https://github.com/jayzalowitz/skytwin/blob/main/docs/evals.md) | Evaluation harness, scenario simulation, calibration metrics | \n| [Launch Plan](https://github.com/jayzalowitz/skytwin/blob/main/docs/launch-plan.md) | Procurement + sequencing to public download links | \n| [Launch-Readiness Report](https://github.com/jayzalowitz/skytwin/blob/main/docs/launch-readiness-report.md) | Historical audit with a current account-free launch override; the claim ledger remains authoritative | \n| [Release Procedure](https://github.com/jayzalowitz/skytwin/blob/main/docs/release-procedure.md) | How the evidence-gated tag workflow verifies and publishes a release | \n| [Beta Claim Ledger](https://github.com/jayzalowitz/skytwin/blob/main/docs/beta-claim-ledger.json) | Machine-checked release contract, evidence, limitations, owners, and stop-ship status | \n\nPublic [source-preview snapshots](https://github.com/jayzalowitz/skytwin/releases)\nuse date-based `source-preview-*` tags and contain source only, not desktop\ninstallers. They are a way to try an exact revision with local development tools;\nthey do not certify the planned public beta. See the\n[release guide](https://jayzalowitz.github.io/skytwin/release.html#source-preview).\n\nThe isolated, account-free fictional-data sample in current source is the supported preview. It lets you evaluate the interaction model, explanations, controls, and boundaries without giving SkyTwin an inbox, credentials, or a provider key. Published unsigned technical-preview installers predate portions of this guarded sample path.\n\nThe [Start guide](https://jayzalowitz.github.io/skytwin/start.html) explains what\nthe installer changes locally. The sample is intentionally separate from real\naccounts: its product views are read-only, and its approve/reject/correct\ninteractions are session-local simulations with no provider, connector, or\nexecution-adapter effects.\n\nA candidate action is evaluated against policy, trust, spend, risk, reversibility, and provenance. A model suggestion is never the authority to run work. Local reasoning does not fall through to a hosted provider. A hosted provider is an explicit network choice. The verified-private boundary admits only explicit interactive TrustedRouter calls after SkyTwin verifies fresh same-session gateway attestation and an exact-byte confidential-route receipt; NEAR AI remains unavailable.\n\nThe guarded current-source sample and future supported beta do not ship a\nsupported managed Google OAuth service. That does **not** mean real-inbox use is\nabsent: the current desktop alpha exposes a five-step Gmail wizard in its\nwindow and serves it at `http://localhost:3200/#/connect-gmail` for already\nauthenticated browser sessions, and a source deployment\ncan enable the retained provider path only with the exact\n`SKYTWIN_GOOGLE_CONNECTION_MODE=experimental` opt-in. The alpha includes a\nSkyTwin-team client ID for initial identity and Calendar authorization, then\nrequires a user-created Google Web Application client for Gmail; a source\noperator supplies the client through environment configuration. Google grants\nthe requested `calendar.events` and `gmail.modify` scopes broad event and\nmailbox-write authority, but SkyTwin's current release claim is ingestion and\nproposals—not supported Gmail send/archive or Calendar mutation. This remains an\nadvanced alpha/experimental path: the alpha's client secret and OAuth tokens\nlack app-level encryption, Google testing-mode grants can expire after seven\ndays, and the current Gmail archive workflow does not claim a complete\nmailbox-mutation runtime. Microsoft code is retained behind the same source flag\nbut has no equivalent supported setup claim.\n\nThe source tree also contains a default-off Gmail archive proposal experiment\n(`SKYTWIN_GMAIL_ARCHIVE_ENABLED=true`) for unsupported account-connected\ndevelopment. It can persist an owner-bound proposal and record an explicit\napproval or rejection, but the response deliberately reports\n`execution: null`: no Gmail mutation caller, recovery worker, or feedback\nprojection is wired into runtime yet. Enabling the flag is not an execution or\nrelease-support claim.\n\nSkyTwin is preparing a desktop-first `v0.7.0-beta`. It is **not release-ready**:\nfresh packaged-sample and managed-model validation, production key management,\nsigned/notarized artifacts, SBOMs, provenance, and clean-machine evidence remain\nstop-ship items. The machine-checked\n[`docs/beta-claim-ledger.json`](https://github.com/jayzalowitz/skytwin/blob/main/docs/beta-claim-ledger.json) is the source of\ntruth for release claims and support status. Current builds remain technical\npreviews; the unsigned alpha packages the guarded sample and BYO Google path but\ndoes not carry verified managed-model or beta evidence. The core decision pipeline,\ntwin model, policy engine, and swappable memory layer are implemented. Google\nconnector and OAuth code ships in the alpha and can be enabled explicitly for an\nexperimental source deployment. Managed\nGoogle access is deferred. Mobile remains a\nsource/development surface rather than part of the beta support matrix.\nThe supported beta topology is one non-demo human owner per installation.\nInstallation credentials and dynamically discovered credential requirements are\nshared installation configuration; local multi-owner and hosted deployments are\noutside the beta support boundary.\n\n**Free and open-source forever for personal use.** Team and hosted tiers are planned for organizations that need shared policies, audit logs, or managed infrastructure — see [`docs/launch-plan.md`](https://github.com/jayzalowitz/skytwin/blob/main/docs/launch-plan.md) for the split.\n\n**What works in the development/source tree today:**\n\n- One-command install (`curl | bash` ) on macOS, Linux, and WSL — installs every dependency, clones the repo, starts the services, opens the dashboard\n- \"Ask your twin\" widget on the dashboard — type any situation, get a predicted action with reasoning and confidence, no accounts required\n- A fully populated development demo seed with mock approval actions, plus a separate guarded sample session in the current packaged alpha. Its database-backed surface is read-only; a dedicated simulation can approve, reject, or correct fixed proposals and demonstrate session-local learning without invoking real connectors, providers, credentials, or execution adapters.\n- Inbox-Intelligence briefing — a daily/weekly digest that splits **to-dos (act)** from**topics (FYI)** , cites the source signal behind every item, persists memory-derived action opportunities, routes them through policy plus IronClaw/OpenClaw/Direct execution, reports queued/executed/blocked/learning-needed outcomes, and offers a \"Power view\" toggle for the technical detail behind each call\n- Versioned signal-digest workflows — teach a read-only Watch in plain language, resolve at most one missing detail, replay the candidate against real owner-scoped signals, explicitly activate an immutable version, propose a minimal correction, compare the replay, and atomically roll back. Every adaptive run pins the exact version, compiled payload, complete-evidence commitment, bounded display snapshot, and the version's sanitized inference identity when model-assisted (or an explicit no-inference state for user-authored revisions); deterministic matching remains available when summary generation does not.\n- Full decision pipeline: signal → interpret → decide → policy check → execute/escalate → explain → learn\n- Mode-scoped model reasoning: on-device embedded/Ollama or an explicitly selected provider chain, with fallback contained inside the selected location boundary, request-scoped local-only enforcement for Ollama, and deterministic rules when no eligible provider responds\n- Twin model with versioned profiles, confidence scoring, and preference learning\n- Policy engine with spend limits, trust tiers, and domain-specific rules\n- Swappable memory backend: SkyTwin's gbrain-compatible implementation is the default, running vector + tsvector RRF directly on CRDB. Upstream gbrain v0.50.5.0 supports PGLite and PostgreSQL, not CockroachDB; its unchanged schema/runtime fails the supported CRDB path on PostgreSQL-specific DDL/functions, and its CLI does not implement SkyTwin's complete write, episode, and graph contract. The real CLI integration is therefore only a programmatic interoperability adapter and is not selected by SkyTwin's runtime factory. Optional hybrid mode adds the legacy spatial Memory Palace (#197). Selectable per-installation via `MEMORY_BACKEND` and per-user via the dashboard. See[`docs/memory-swap.md`](https://github.com/jayzalowitz/skytwin/blob/main/docs/memory-swap.md) .\n- Web dashboard for reviewing decisions, managing preferences, configuring AI providers, and auditing\n- Desktop build targets for macOS, Windows, and Linux; current artifacts are unsigned and not yet in the beta support matrix\n- Mobile source/development app (iOS, Android) with QR pairing, push notifications, and voice capture that sends audio to the paired desktop for transcription\n- Local model backends for llama.cpp text, whisper.cpp STT, and Piper TTS (`/api/voice/transcribe` and`/api/voice/synthesize` ); each backend is on-device only when its compatible binary and model are present\n- SSRF-safe URL validation for all LLM provider endpoints, with DNS rebinding protection\n- Dynamic adapter discovery for third-party execution plugins\n- Repository-wide tests and packaging workflows on GitHub Actions\n\n**What's next:**\n\n- More connectors (Slack, Notion, bank feeds)\n- Hosted version with multi-tenant support\n- Improved preference learning from implicit signals\n\nWe welcome contributions. See [CONTRIBUTING.md](https://github.com/jayzalowitz/skytwin/blob/main/CONTRIBUTING.md) for guidelines on getting started, running tests, and submitting pull requests.\n\nFound a vulnerability? See [SECURITY.md](https://github.com/jayzalowitz/skytwin/blob/main/SECURITY.md) for responsible disclosure instructions.\n\n[Apache License 2.0](https://github.com/jayzalowitz/skytwin/blob/main/LICENSE) — use it, modify it, build on it.\n\n**Free and open source forever for personal use.** Future Team and Hosted tiers are planned for organizations that need shared policies, audit logs, or managed infrastructure. Personal features will never be paywalled.\n\nNo prices today — we're not ready to commit numbers, and overpromising on a backlog you haven't shipped is the easiest trust to lose. The shape of the future, not the price list.", "url": "https://wpnews.pro/news/show-hn-i-made-a-free-and-open-source-muse-instinct", "canonical_source": "https://github.com/jayzalowitz/skytwin", "published_at": "2026-09-23 19:22:43+00:00", "updated_at": "2026-09-23 19:30:57.542627+00:00", "lang": "en", "topics": ["artificial-intelligence", "ai-agents", "ai-products", "ai-tools"], "entities": ["SkyTwin", "Google", "Gmail", "jayzalowitz", "GitHub"], "alternates": {"html": "https://wpnews.pro/news/show-hn-i-made-a-free-and-open-source-muse-instinct", "markdown": "https://wpnews.pro/news/show-hn-i-made-a-free-and-open-source-muse-instinct.md", "text": "https://wpnews.pro/news/show-hn-i-made-a-free-and-open-source-muse-instinct.txt", "jsonld": "https://wpnews.pro/news/show-hn-i-made-a-free-and-open-source-muse-instinct.jsonld"}}