Hosts, connections and workspaces

Four words carry most of ShellCanvas: host, connection, workspace and service. They are not synonyms, and knowing which is which explains what survives a reconnect, what an app can reach, and why an action is sometimes unavailable.

How it works

Host

A host is a saved description of how to reach a machine: name, address, port, user name and the path to a private key. It is a piece of local configuration, not a live thing. Hosts live in your application data, and passwords and passphrases are never part of them. Entries imported from ~/.ssh/config appear alongside the ones you saved, in their own group.

Connection

A connection is one live transport to one machine — for SSH, the authenticated session, established only after the host key has been checked. Channels are opened on it: a PTY for each terminal, SFTP for file work. A connection can be lost without your work being lost, and a reconnect creates a new connection while the workspace stays where it was.

Each connection carries an identity that includes a generation number, so results from an older connection cannot be applied after a reconnect. That is why a stale window refreshes rather than showing content from a session that no longer exists.

Workspace

A workspace is the local desktop state for one target: its windows, their positions, the folders you opened, terminal output, editor drafts and which apps are running. Workspaces are what the host pill switches between, and there is always a Local desktop workspace for apps that need no server.

What a workspace keeps is deliberate:

Action	Connection	Windows and drafts
Switch workspace	Stays connected	Kept, restored when you switch back
Disconnect	Released	Kept, including unsaved editor drafts
Reconnect	New connection, fresh shells	Kept; Files re-reads its folder
Close workspace	Released	Discarded, after a warning about unsaved work
Quit	Released	Discarded; layouts are not restored on the next run

Service

A service is one capability a connection provides: files, a console, remote settings, or a namespaced custom service from an adapter. Apps and built-in windows ask the workspace for a service rather than for "SSH", which is why the same Files window can work over a different transport later, and why a feature can be unavailable while everything else keeps working — a server without SFTP has a console but no file service.

Each service is bound to a source connection. A workspace can, in principle, take its file service from one connection and its console from another; today SSH supplies the full set, and installed adapters can supply their own services. When a service disappears — capability lost, connection dropped — the windows that used it stay open, explain the state and let you recover local work such as an unsaved draft.

How they fit together

host (saved details)
  └── connection (live, authenticated, one per workspace)
        ├── files service      → Files, Editor, transfers
        ├── console service    → Terminal windows
        ├── settings service   → Host details
        └── custom services    → installed adapters
workspace (windows, folders, drafts) ── switched from the host pill

Boundaries

• One connection per workspace. Connecting to the same machine twice gives you two workspaces, each with its own session number.
• Reconnect is not resume. Shells start fresh: a process you left running in a terminal keeps running on the server, but its output is no longer attached to your window. Terminal multiplexers such as tmux are unaffected and remain the way to keep long jobs.
• Workspace state is in memory. It survives switching and disconnecting for as long as the app runs, and is gone after a restart or a crash. Editor drafts are kept in memory too; crash recovery does not exist yet.
• Saved workspace profiles record bindings, never secrets. They describe which sources supply which services, so you re-authenticate when you open them.
• Composition is real but sparsely populated. The model supports several sources in one workspace, and installed native adapters can provide services. Production adapters for serial consoles, Telnet, FTP or device APIs are not implemented; SSH is what ships.

Related guides

• Workspaces and profiles — using several machines at once.
• Disconnect and reconnect — what happens when a connection drops.
• Saved hosts and SSH config — where hosts come from.
• Connection and workspace model — the same model from the implementation's side.