Workspace Sessions

Overview

Workspaces in Netcatty allow you to organize multiple terminal sessions in split-pane layouts. You can create complex arrangements, save them for later, and restore entire session states with a single click.

Understanding Workspaces

A workspace is a container for one or more terminal sessions arranged in a flexible layout.

Workspace Structure

Workspace

object

Show Properties

string

required

Unique workspace identifier (format: ws-{uuid})

title

string

required

Workspace name displayed in the tab

root

WorkspaceNode

required

Root node of the layout tree (pane or split)

viewMode

WorkspaceViewMode

Layout mode: split (tiled) or focus (list + single terminal)

focusedSessionId

string

Currently focused session ID (used in focus mode)

snippetId

string

Reference to snippet if workspace was created from snippet runner

Workspace Nodes

Workspaces are built from two types of nodes:

Pane Node
Split Node

A leaf node containing a single terminal session.

{
  id: "pane-abc123",
  type: "pane",
  sessionId: "session-xyz789"
}

A container node that arranges child nodes in a direction.

{
  id: "split-def456",
  type: "split",
  direction: "vertical", // or "horizontal"
  children: [
    { type: "pane", sessionId: "session-1" },
    { type: "pane", sessionId: "session-2" }
  ],
  sizes: [0.5, 0.5] // Relative sizes (sum to 1.0)
}

Creating Workspaces

From Existing Sessions

Combine two or more terminal tabs into a workspace. UI Workflow:

Open multiple terminal sessions as separate tabs
Right-click on a tab
Select Create Workspace from Tabs
Choose which tabs to include
Select initial layout (horizontal or vertical)
Click Create

Netcatty merges the selected tabs into a single workspace tab with split panes.

From Snippet Runner

Run a snippet across multiple hosts simultaneously. UI Workflow:

Navigate to Snippets
Select a snippet
Click Run on Multiple Hosts
Select target hosts
Click Run

Netcatty creates a workspace with:

One pane per host
Side-by-side layout
Snippet execution in each pane

Example:

const workspace = createWorkspaceFromSessionIds(
  ['session-web01', 'session-web02', 'session-db01'],
  {
    title: 'Deploy to Production',
    viewMode: 'split',
    snippetId: 'deploy-script'
  }
);

// Result:
// ┌─────────┬─────────┬─────────┐
// │ web-01  │ web-02  │  db-01  │
// │         │         │         │
// └─────────┴─────────┴─────────┘

View Modes

Split View (Default)

Tiled layout with all sessions visible simultaneously.

viewMode

split

Display all panes in a split layout

Best for:

Monitoring multiple servers
Running parallel commands
Comparing output across hosts

Focus View

List of sessions on the left, single focused terminal on the right.

viewMode

focus

List view with one terminal in focus

Best for:

Many sessions (5+)
Switching between servers frequently
Limited screen space

Switching Modes: Click the view mode toggle in the workspace toolbar:

Grid icon = Split view
List icon = Focus view

Layout Management

Splitting Panes

Divide a pane into two sections. Horizontal Split (top/bottom):

Right-click in terminal → Split Horizontal
Keyboard: Cmd+D (Mac) / Ctrl+Shift+D (Windows/Linux)

Vertical Split (left/right):

Right-click in terminal → Split Vertical
Keyboard: Cmd+Shift+D (Mac) / Ctrl+Shift+E (Windows/Linux)

Example:

Initial:          After Vertical Split:    After Horizontal Split:
┌─────────┐      ┌────────┬────────┐      ┌────────┬────────┐
│         │      │        │        │      │        │   ┌────┤
│  Pane   │  →   │ Pane 1 │ Pane 2 │  →   │ Pane 1 │   │ P3 │
│         │      │        │        │      │        │   └────┤
└─────────┘      └────────┴────────┘      └────────┴────────┘

Resizing Panes

Mouse:

Hover over the divider between panes
Cursor changes to resize icon
Click and drag to adjust size

Sizes are automatically saved as relative proportions in the workspace.

Closing Panes

Close individual panes without destroying the workspace. Methods:

Click × on pane’s tab
Keyboard: Cmd+W (Mac) / Ctrl+W (Windows/Linux)
Right-click → Close Pane

Behavior:

When closing a pane from a split, the sibling pane expands to fill the space
When closing the last pane, the workspace tab closes

Navigating Workspaces

Focus Management

Move keyboard focus between panes.

focusedSessionId

string

ID of the currently focused session

Keyboard Navigation:

Action	Mac	Windows/Linux
Move focus up	`Cmd+Opt+↑`	`Ctrl+Alt+↑`
Move focus down	`Cmd+Opt+↓`	`Ctrl+Alt+↓`
Move focus left	`Cmd+Opt+←`	`Ctrl+Alt+←`
Move focus right	`Cmd+Opt+→`	`Ctrl+Alt+→`

Focus Algorithm: Netcatty uses spatial navigation:

Determines pane positions based on layout tree
Finds panes in the requested direction
Selects the closest pane by center point
Wraparound: If no pane exists in direction, wraps to opposite edge

Example:

┌─────┬─────┐
│  1  │  2  │
├─────┼─────┤
│  3  │  4  │
└─────┴─────┘

From Pane 1:
- Right → Pane 2
- Down → Pane 3
- Left → Wraps to Pane 2
- Up → Wraps to Pane 3

Click anywhere in a pane to focus it.

Saving Workspaces

Workspaces are automatically saved when you:

Create a split
Resize panes
Close a pane
Change view mode

Persistence:

Workspace layout is stored in Netcatty’s database
Session states are not stored (terminal content is ephemeral)
Connection details are preserved via host references

Restoring Workspaces

Reopen a saved workspace to recreate the layout and reconnect to hosts.

From Recent Workspaces

Click Workspaces in the sidebar
View list of saved workspaces
Click on a workspace to restore

Netcatty will:

Recreate the split layout
Reconnect to each host
Restore pane sizes
Apply the saved view mode

From Snippets

If a workspace was created from a snippet:

Navigate to Snippets
Click on the snippet
Select Restore Workspace
Netcatty reloads the workspace and re-runs the snippet

Terminal content (command history, output) is not preserved. Only the layout and connection details are restored.

Session State

Terminal Sessions

TerminalSession

object

Show Properties

string

required

Unique session identifier

hostId

string

required

Reference to host configuration

hostLabel

string

required

Display name

username

string

required

SSH username

hostname

string

required

Target hostname/IP

status

string

required

Connection status: connecting, connected, or disconnected

workspaceId

string

ID of parent workspace (if in a workspace)

startupCommand

string

Command to run after connection

protocol

HostProtocol

Protocol override for this session

port

number

Port override for this session

Session Lifecycle

Advanced Workspace Features

Broadcast Mode

Send input to all panes in a workspace simultaneously. Activation:

Click Broadcast icon in workspace toolbar
Keyboard: Cmd+B (Mac) / Ctrl+B (Windows/Linux)

Use Cases:

Run same command across multiple servers
Parallel software updates
Synchronized configuration changes

Broadcast mode affects all panes in the workspace. Use carefully in production.

Nested Layouts

Create complex layouts by nesting splits. Example:

{
  type: "split",
  direction: "horizontal",
  children: [
    {
      type: "split",
      direction: "vertical",
      children: [
        { type: "pane", sessionId: "web-01" },
        { type: "pane", sessionId: "web-02" }
      ],
      sizes: [0.5, 0.5]
    },
    { type: "pane", sessionId: "db-01" }
  ],
  sizes: [0.66, 0.34]
}

Visual Result:

┌────────────┬─────┐
│   web-01   │     │
├────────────┤ db  │
│   web-02   │     │
└────────────┴─────┘

Dynamic Pane Addition

Add new panes to an existing workspace. Methods:

Split an existing pane (creates sibling)
Drag a tab into the workspace
Right-click workspace → Add Pane → Select host

Workspace Examples

Example 1: Three-Server Monitoring

{
  "id": "ws-monitoring",
  "title": "Production Monitoring",
  "viewMode": "split",
  "root": {
    "type": "split",
    "direction": "vertical",
    "children": [
      { "type": "pane", "sessionId": "web-01" },
      { "type": "pane", "sessionId": "web-02" },
      { "type": "pane", "sessionId": "db-01" }
    ],
    "sizes": [0.33, 0.33, 0.34]
  }
}

Example 2: Development Workspace

{
  "id": "ws-dev",
  "title": "Development Environment",
  "viewMode": "split",
  "root": {
    "type": "split",
    "direction": "horizontal",
    "children": [
      {
        "type": "split",
        "direction": "vertical",
        "children": [
          { "type": "pane", "sessionId": "dev-server" },
          { "type": "pane", "sessionId": "logs" }
        ],
        "sizes": [0.6, 0.4]
      },
      { "type": "pane", "sessionId": "database" }
    ],
    "sizes": [0.7, 0.3]
  }
}

Best Practices

Workspace Organization

Group related servers (e.g., all web servers, all databases)
Use descriptive workspace names
Create workspace templates for common scenarios

Layout Design

Keep layouts simple (2-4 panes for most tasks)
Use horizontal splits for wide terminals (code/logs)
Use vertical splits for narrow terminals (monitoring)

Performance

Limit active workspaces to 1-2 at a time
Close disconnected sessions
Use focus view for 5+ panes

Broadcast Mode

Test commands on a single pane first
Use with read-only operations when possible
Disable broadcast after use to prevent accidents

Troubleshooting

Workspace Not Saving

Solution:

Check Netcatty’s data directory permissions
Verify disk space is available
Restart Netcatty to flush database

Session Won't Reconnect on Restore

Possible Causes:

Host configuration was deleted
Authentication credentials changed
Network connectivity issues

Solution:

Verify host still exists in Hosts page
Check authentication settings
Try connecting to host directly first

Pane Sizes Not Preserved

Solution:

Ensure you wait for auto-save after resizing
Manually close and reopen workspace to test
Check browser console for errors

Split Terminals

Keyboard shortcuts and pane management

Snippets

Run commands across multiple hosts

Keyboard Shortcuts

Master workspace navigation shortcuts

Get Started

Core Features

Guides

Integrations

Advanced

​Overview

​Understanding Workspaces

​Workspace Structure

​Workspace Nodes

​Creating Workspaces

​From Existing Sessions

​From Snippet Runner

​View Modes

​Split View (Default)

​Focus View

​Layout Management

​Splitting Panes

​Resizing Panes

​Closing Panes

​Navigating Workspaces

​Focus Management

​Mouse Navigation

​Saving Workspaces

​Restoring Workspaces

​From Recent Workspaces

​From Snippets

​Session State

​Terminal Sessions

​Session Lifecycle

​Advanced Workspace Features

​Broadcast Mode

​Nested Layouts

​Dynamic Pane Addition

​Workspace Examples

​Example 1: Three-Server Monitoring

​Example 2: Development Workspace

​Best Practices

​Troubleshooting

​Related Resources

Split Terminals

Snippets

Keyboard Shortcuts

Overview

Understanding Workspaces

Workspace Structure

Workspace Nodes

Creating Workspaces

From Existing Sessions

From Snippet Runner

View Modes

Split View (Default)

Focus View

Layout Management

Splitting Panes

Resizing Panes

Closing Panes

Navigating Workspaces

Focus Management

Mouse Navigation

Saving Workspaces

Restoring Workspaces

From Recent Workspaces

From Snippets

Session State

Terminal Sessions

Session Lifecycle

Advanced Workspace Features

Broadcast Mode

Nested Layouts

Dynamic Pane Addition

Workspace Examples

Example 1: Three-Server Monitoring

Example 2: Development Workspace

Best Practices

Troubleshooting

Related Resources