float — runtime environments for SLICC

Synopsis

Floats are the runtime environments SLICC runs in. Each float provides the same core agent capabilities (VFS, shell, tools, CDP browser control) but differs in how it launches, connects to Chrome, and handles security constraints.

CLI Float

The CLI float is the standalone server mode. An Express server launches a Chrome instance, proxies CDP over WebSocket, and serves the webapp UI. Layout is a resizable split with all panels visible (chat, terminal, files, memory).

• UI port

  5710 (default, override with PORT env var)

• Chrome CDP port

  9222 (auto-detected from Chrome stderr; passed as port 0 to let Chrome pick)

• Vite HMR port

  24679 (dev mode only)

• CDP transport

  WebSocket — full bidirectional connection to Chrome DevTools Protocol

Chrome is launched with an isolated user-data directory keyed by the serve port. This means multiple CLI instances can run simultaneously without conflicting profiles.

Multiple CLI Instances

Override the PORT env var to run parallel instances. Each gets its own Chrome profile, CDP port (auto-resolved), and HMR port:

PORT=5720 npm run dev   # Second instance
PORT=5730 npm run dev   # Third instance

No shared state between instances.

Chrome Extension Float (MV3)

The extension float runs as a Manifest V3 Chrome extension with three execution layers:

• Side panel

  The visible UI. Compact tabbed interface. Has its own WasmShell instance (powers the terminal tab). Manages Layout and DOM.

• Service worker

  Message relay between side panel and offscreen document. Proxies CDP commands via chrome.debugger API. Routes chrome.runtime messages.

• Offscreen document

  Runs the agent engine (Orchestrator, VFS, BrowserAPI). Has its own WasmShell instance (executes bash tool calls). Survives side panel close/reopen — the agent keeps working even when the panel is closed.

Key constraint: the extension has two separate shell instances. The side panel shell and the offscreen shell share IndexedDB but NOT window globals. Communication between layers goes through chrome.runtime messages routed by the service worker.

Zero server required — the extension runs entirely in the browser. CDP access uses the chrome.debugger API instead of WebSocket.

Strict CSP applies. Dynamic code execution (eval, new Function) is blocked. Use sandbox.html as the workaround for dynamic code. Use sprinkle-sandbox.html for sprinkle/widget rendering. Use chrome.runtime.getURL() for bundled assets.

Electron Float

The Electron float reuses the CLI server in --serve-only mode and injects an overlay shell into an Electron BrowserWindow. It attaches to a target app's CDP endpoint.

• Default CDP port

  9223

• Default serve port

  5710

• Launch command

  npm run dev:electron -- /Applications/SomeApp.app

The server spawns in --serve-only mode with the specified --cdp-port, then the Electron main process creates a BrowserWindow loading the target URL with the SLICC overlay injected.

Sliccstart Float

Sliccstart is a native macOS SwiftUI launcher application. It provides a GUI for launching SLICC instances in both standalone CLI and Electron modes. Each launched app gets dynamically allocated ports (hash-based with fallback). Lives in packages/swift-launcher/.

Cloud Float

Planned. Not yet implemented.

Capability Comparison

                CLI          Extension      Electron
CDP transport   WebSocket    chrome.debugger WebSocket
Server needed   Yes          No             Yes (--serve-only)
CSP             Relaxed      Strict (MV3)   Relaxed
Shell instances 1            2 (panel+offscreen)  1
Network access  Full         Extension-scoped Full
Survives close  No           Yes (offscreen) No
Multi-instance  PORT=NNNN    Single          Per-app ports

See Also

scoop(1) — sub-agent isolation. cone(1) — the main agent. lick(1) — external event triggers.