Spindle

Spindle is a local macOS runtime for agent workspaces, memory, skills, browser control, and authenticated remote MCP access. It keeps control, pairing, browser, and state services on loopback. Only the OAuth-protected MCP endpoint may be exposed through a Cloudflare Tunnel.

Current platform

Spindle v0.1 supports macOS on Apple silicon. Windows and Linux are outside the current certification scope.

Requirements:

• macOS
• Node.js 22 through 26
• Google Chrome for browser control

Install

Install the public npm package, then launch Spindle once:

npm install --global spindle-mcp
spindle

The first-run wizard installs and starts the private macOS LaunchAgent runtime from inside the interface. The npm package name is spindle-mcp; the installed commands remain spindle and spindled.

For direct release installation, verify the supplied SHA-256, extract the self-contained macOS tarball, and run its bootstrap CLI:

shasum -a 256 -c spindle-0.1.6-macos-arm64.tgz.sha256
tar -xzf spindle-0.1.6-macos-arm64.tgz
node package/bin/spindle.js

The installer creates:

• immutable releases under ~/Library/Application Support/Spindle/releases
• current as an atomic release pointer
• command links under ~/.local/bin
• a private user LaunchAgent at ~/Library/LaunchAgents/com.spindle.runtime.plist
• user data under ~/.spindle

Add ~/.local/bin to PATH when necessary.

First run

Run spindle. The full-screen, resumable wizard is the one-stop setup surface for:

• local runtime installation and startup
• allowed workspace roots
• compatible skills, instructions, and memory import from supported agent harnesses
• a dedicated Spindle Browser profile with persistent website sign-ins and cookies
• owner authentication
• local, temporary, or named Cloudflare access
• Standard or YOLO permissions
• final initialization and doctor verification

No follow-up setup commands are required. Existing external files are imported or synchronized without being overwritten.

Runtime lifecycle

spindle start
spindle stop
spindle restart
spindle status --json

Installed releases use the user LaunchAgent. Development checkouts use the local detached supervisor.

Spindle Browser

The supported browser mode is a separate visible Google Chrome profile managed by Spindle. During first-run setup, Spindle opens that profile without requiring a Google account or website sign-in. Users may close the window immediately; Spindle reopens the same profile when browser work is needed. Any cookies, local storage, downloads, and website sessions added later remain available across runtime restarts without reading or copying the user's normal Chrome profile.

Browser control uses a loopback-only Chrome DevTools connection and reopens the same profile automatically when an agent needs it. spindle browser open, spindle browser status, and spindle browser close remain available after setup. Incognito is never launched or exposed. Browser sessions and workflow recordings persist in SQLite.

The existing Chrome extension source and packaged build remain available for experimental development. It is outside onboarding and is not a supported browser provider in v1.

Permissions

Standard mode requires a one-time approval for consequential browser actions. Each approval is bound to the exact command, client, and Chrome profile.

spindle approvals
spindle yolo on
spindle yolo off

YOLO mode bypasses browser confirmation only. It does not bypass authentication, allowed roots, schema validation, managed-profile isolation, incognito exclusion, unsupported-page restrictions, sensitive-value redaction, or global-memory approval. Persistent YOLO requires the exact confirmation text ENABLE YOLO.

Memory, skills, workflows, and identity

spindle memory list
spindle skills list
spindle sync status
spindle workflows list
spindle graph export
spindle identity export --output identity.spindle

Session and project memories may be stored automatically. Global memory always requires approval. Recorded browser workflows become disabled managed skill drafts and must be reviewed before enablement. Portable identity bundles exclude local authentication and OAuth secrets and may be passphrase-encrypted.

Remote MCP access

Quick Tunnels are temporary testing tools. A stable named tunnel uses your own Cloudflare account and a domain already active in that account. The first-run wizard can install the verified managed binary, open browser authorization, create the tunnel, route DNS, and start it without asking the user to leave setup.

Spindle never asks for or stores a Cloudflare password, API token, account ID, account certificate, or tunnel credentials. spindle cloudflare commands remain available for later management and automation. Spindle stores only non-secret tunnel identifiers and status, and invokes cloudflared with the current loopback MCP URL. Custom cloudflared config files are rejected so this command cannot expose unrelated local services.

spindle cloudflare quick
spindle cloudflare stop

The control API, browser bridge, and pairing API remain bound to 127.0.0.1. Cloudflare exposes only the OAuth-protected MCP route.

Update and uninstall

Updates require a local release archive and its exact SHA-256:

spindle update --package spindle-0.1.6-macos-arm64.tgz \
  --sha256 <64-character-sha256>

Activation is atomic and health-checked. A failed release restores the previous release and prior running state.

Ordinary uninstall preserves ~/.spindle:

spindle uninstall

Permanent data removal requires explicit confirmation:

spindle uninstall --purge-data \
  --confirm-purge "PURGE SPINDLE DATA"

Development verification

npm ci
npm run typecheck
npm test
npm run build
npm run build:release
npm run smoke:release

Release construction creates an exact file manifest, rejects symlinks and unsafe archive entries, bundles the native SQLite binary, excludes source maps and declarations, and supports an offline smoke installation.

Security and provenance

Spindle is designed as remote access to explicitly allowed local folders. Treat its owner token, control token, pairing secrets, OAuth tokens, tunnel credentials, and identity-bundle passphrases as sensitive.

Spindle includes MIT-licensed upstream code. See NOTICE and THIRD_PARTY_NOTICES.md for attribution and dependency licenses.

License

MIT. See LICENSE.