Quick Start

Quick Start

A five-minute tour. By the end you'll have a workspace with a local terminal, an SSH session attached to tmux, a browser pane, and an AI co-pilot that can drive them.

Assumes you've completed Installation and have npm run dev running.

---

1. Create a workspace (15 s)

On first launch you'll see an empty state with Create Workspace. Click it (or Ctrl+T), pick a grid (start with 2×2), give it a name like dev.

The grid is the layout. Each cell is a pane. Drag the gutters between cells to resize; drag a pane label to swap two panes. Resizing and swapping is reversible and saves automatically.

More: Workspaces-and-Layout

---

2. Make one pane a terminal (10 s)

Right-click any empty pane → Terminal → pick a template (e.g., PowerShell on Windows, bash on Unix). Type a few commands to confirm it works.

Ctrl+Shift+C copies your selection; Ctrl+V pastes (bracketed-paste-aware); Ctrl+C always sends SIGINT, never copies. If terminal mouse-mode is interfering with native text selection, click the pane label menu and toggle Disable App Mouse.

More: Terminal-Panes

---

3. Add an SSH+tmux session (60 s)

1. Open the SSH Server Manager: status bar → SSH button (or right-click pane → SSH Servers).
2. Click Add Server, fill in host / user / auth (key path or password). Save.
3. Right-click any empty pane → SSH → pick your server.

ClusterSpace runs ssh -t user@host tmux new-session -A -s <session-name> automatically. The session name is unique per pane, so two panes connecting to the same host don't echo into each other.

To attach to a session you created elsewhere (or before), right-click the pane → Attach to tmux session… and pick from the list (or type one manually).

More: SSH-and-tmux

---

4. Open a browser pane (15 s)

Right-click an empty pane → Browser. Enter a URL in the address bar at the top.

The browser pane is a full Chromium webview with back/forward/reload, bookmarks, history, downloads, find-in-page, and multi-tab. Drag the title bar to move/swap the pane.

For saved logins: click the pane menu → Saved Logins → Add to store an origin/username/password. Use Fill saved login later to inject credentials into focused inputs (never auto-submits).

More: Browser-Panes · Saved-Logins

---

5. Wake the AI (60 s)

Ctrl+Shift+A opens the AI chat panel. The first time, it'll prompt you to configure a provider.

Easy options:

• Ollama (local, free) — install Ollama, ollama pull llama3.1:8b, then in ClusterSpace use Discover with the host localhost to auto-find it.
• Claude — endpoint https://api.anthropic.com/v1, model claude-sonnet-4-5, paste your API key.
• OpenAI — endpoint https://api.openai.com/v1, model gpt-4o-mini, paste your API key.

Test it: type list the panes in this workspace and hit Enter. The model should call the list_panes tool and show you what's open.

More: AI-Providers · AI-Overview · AI-Tools-Reference

---

6. Have the AI drive a pane (60 s)

In the chat: "In pane 1, run ls -la and tell me what you see."

The AI will call write_to_terminal on the target pane, then read_terminal_output after a short wait, then summarize. The pane label gets a pulsing blue dot while the AI is working in it.

More: Agent-Orchestration · Fleet-Dashboard

---

7. (Optional) Launch a goal (90 s)

The goal runner is autonomous — the AI keeps working until a success criterion is met. Open the Goal Dashboard with Ctrl+Shift+G → + New Goal.

Example: goal = "Install nginx and verify it serves the default page on port 80", success criterion = shell curl -sf http://localhost, risk = write_local, wall clock = 15 minutes.

Click Start Goal. The dashboard shows live steps, critic verdicts ("PROGRESSING"/"STUCK"/"ACHIEVED"), and verification results. The AI can't stop on its own — it has to call claim_complete and pass the curl check.

More: Goal-Runner-Overview · Starting-a-Goal · Success-Criteria

---

Where to go next

Want to…	Read
Memorize hotkeys	Keyboard-Shortcuts
Configure local LLMs	AI-Providers
Author a custom persona	Writing-Personas
Write a plugin tool	Plugin-Authoring
Understand the architecture	Architecture-Overview

---

See also

• Installation — prereqs and build
• Troubleshooting — when things break
• FAQ — common questions