Skip to content

FAQ

Jump to bottom
nick3 edited this page May 28, 2026 · 1 revision

FAQ

Short answers. See linked pages for depth.

General

Q: What is ClusterSpace? A desktop app that combines terminals, embedded browsers, and an optional AI co-pilot into a tiled workspace with persistent SSH sessions and per-pane agents. See Home.

Q: Is it free? Yes. MIT licensed. AI provider costs (if any) are paid to your chosen provider — ClusterSpace itself doesn't charge.

Q: Does it work offline? The app works fully offline. The AI works only if your provider is local (Ollama, LM Studio). For Claude / OpenAI, you need internet.

Q: What platforms? Windows, macOS, Linux. Built on Electron.

Setup

Q: Can I use OpenAI? Yes. Set endpoint https://api.openai.com/v1, model gpt-4o (or any tool-calling model). See AI-Providers.

Q: Can I use Claude? Yes. Set endpoint https://api.anthropic.com/v1, model claude-sonnet-4-5. See AI-Providers.

Q: Can I use Ollama / LM Studio? Yes. Use the Discover button or set endpoint http://localhost:11434/v1 (Ollama) or http://localhost:1234/v1 (LM Studio). Not every model supports tool calling — check the provider's docs.

Q: Do I need tmux? Only on remote hosts if you want SSH session persistence. Local terminal panes don't use it. See SSH-and-tmux.

Q: Where does my data live? <userData>/clusterspace-data/ — paths vary by OS. See Data-Storage-and-Migration.

AI

Q: How do I disable the AI? Don't configure a provider. The chat panel won't do anything. Or just don't open it (Ctrl+Shift+A).

Q: Is my data sent anywhere? Only to the AI provider you choose, only when you use the AI. The app itself doesn't phone home. Local providers (Ollama, LM Studio) keep data on your machine entirely.

Q: Can the AI see my screen / files / SSH credentials? Only what tools let it see:

  • Terminal output via read_terminal_output
  • Browser page content via browser_get_content / get_axtree
  • Screenshots via capture_screenshot / browser_screenshot
  • It cannot read filesystem directly (no read_file tool) without you typing cat into a pane
  • It cannot read SSH passwords (they're typed by the main process, not exposed to tools)
  • It cannot read saved browser logins (same — typed by main process)

Q: Can the AI delete my files? If you give it write_local policy on a goal and don't sandbox, it can rm things via write_to_terminal. Use Goal-Policy-and-Risk-Levels to constrain it, or stay in read_only.

Q: How do I stop a runaway AI?

  • Chat panel: Esc cancels the current stream
  • Goal runner: open the Goal-Dashboard → Abort
  • Nuclear option: kill the ClusterSpace process

Q: Can I add my own tools? Yes. Drop a .js file in <userData>/clusterspace-data/config/tools/. See Plugin-Authoring.

Panes & Workspaces

Q: Can a pane be SSH'd into a Windows host? Yes — anything OpenSSH can reach. WinRM-only hosts aren't supported.

Q: Can I share workspaces with teammates? Yes — export as .clusterspace.json (no secrets included), share, they import. See Workspaces-and-Layout.

Q: Why are my old tmux sessions named fleet-term-*? The app was renamed. Your old remote sessions kept their names. The SSH-and-tmux shows a "Legacy suggestion" to attach to them.

Q: Can two panes share the same tmux session? Yes — both panes use the same session name via the picker → Attach to tmux session. Note: both will display the same content because they're the same tmux client.

Q: Why don't switching workspaces kill my long-running command? PTYs are backgrounded, not killed. This is intentional. See Workspaces-and-Layout.

Browser

Q: Does it support extensions? No. The webview is bare Chromium. Extensions are a Chrome feature, not Electron's.

Q: Why does Google sign-in fail? Google blocks "automation-detected" user agents. Change the pane's UA to a stock Chrome string via the pane menu → User Agent → presets.

Q: Can I save form-fill data per site? For username/password yes (Saved-Logins). For other form data, no — that'd require Chromium-style form-fill, which isn't built in.

Q: How do I get to DevTools for a browser pane? Right-click pane → Open DevTools, or Ctrl+Shift+I while focused.

Goals

Q: What's the difference between the chat panel and the goal runner? Chat panel: you ask, AI responds (with tools), loop ends when AI stops. Goal runner: you specify a verifiable end state, AI loops until verified. See Goal-Runner-Overview.

Q: What happens if my goal hits the wall-clock cap? Goal ends as failed with message "Wall-clock cap exceeded." The pane is freed.

Q: Can I pause a goal? There's API support (pauseRequested), but no UI button yet. Roadmap.

Q: Can goals run while the app is closed? No. The runner needs the app process. Goals abort when you quit.

Q: Can multiple goals run at once? The infrastructure supports it but findActiveForCurrentCaller picks the most recent goal for transient tool calls (claim_complete, abort_with_report). Practically, run one at a time for now.

Costs

Q: How expensive is the goal runner? Depends on your provider. Each step = one model call + tool calls (free). For Claude Sonnet at ~$3/1M input tokens, a 30-step goal runs ~$0.10-0.50. For Ollama, free.

Q: How do I reduce cost?

  • Use a cheap critic provider (criticProviderId field on goals)
  • Run goals on local models when possible
  • Set lower wallClockMs caps to prevent runaway

Misc

Q: Light theme? Not yet. Roadmap.

Q: Can I customize keybindings? Not in-app yet. Edit src/renderer/hooks/useKeyboardShortcuts.ts and rebuild.

Q: Mobile / web version? Not planned. Desktop-first by design.

Q: How do I report a bug? https://github.com/mtecnic/clusterspace/issues. Include OS, ClusterSpace version, repro steps, and any console errors (DevTools Ctrl+Shift+I).

See also

ClusterSpace · Issues · Releases · MIT License · Edit any page via the Edit button (top right of the wiki).

Start here

User guide

AI subsystem

Goal Runner

Developer

Reference

Clone this wiki locally