sesy

Run your remote SSH Electron project in a local window, instantly.

sesy is the local half of the workflow. It assumes your remote Electron project is already exposing a renderer server over SSH port forwarding, then restores the part the browser cannot: a native Electron desktop window on your machine.

Repository: https://github.com/xgauravyaduvanshii/sesy.git
Author: xgauravyaduvanshii <[email protected]>

Why sesy exists

Web apps are easy over SSH. Forward localhost:3000, open Chrome, and keep coding. Electron apps are different because the renderer is only half the experience. You still need a native Electron shell and BrowserWindow, and Chrome cannot stand in for that.

sesy closes that gap by turning a forwarded renderer URL back into a local Electron app session.

Core workflow

flowchart LR
    A[Remote renderer dev server] --> B[SSH forwarded localhost port]
    B --> C[sesy watch]
    C --> D[Port responds]
    D --> E[Local Electron child process]
    E --> F[BrowserWindow loads forwarded URL]

Quick start

1. Install

npm i @xgauravyaduvanshii/sesy

2. Initialize a project

sesy init

3. Start the remote Electron renderer

npm run dev

4. Make sure the port is forwarded

Typical example:

ssh -L 8000:localhost:8000 your-server

5. Open the local window

sesy watch

Commands

| Command | Purpose | Typical use | |---|---|---| | sesy init | create .sesy.json | first setup in a project | | sesy watch | wait for the renderer and launch Electron | everyday development | | sesy status | inspect current config and environment | quick diagnostics | | sesy doctor | run setup checks with fix hints | troubleshooting |

Command flow

sequenceDiagram
    participant User
    participant Sesy
    participant Config as .sesy.json
    participant Port as localhost port
    participant Bridge as bridge-main.cjs
    participant Electron

    User->>Sesy: sesy watch
    Sesy->>Config: load config
    Sesy->>Port: poll with native http.get()
    Port-->>Sesy: any HTTP response
    Sesy->>Bridge: write temp bridge script
    Sesy->>Electron: spawn local electron process
    Electron-->>User: native desktop window

Project structure

cli/
├── bin/sesy.js
├── src/
│   ├── commands/
│   │   ├── init.js
│   │   ├── watch.js
│   │   ├── status.js
│   │   └── doctor.js
│   ├── core/
│   │   ├── config.js
│   │   ├── watcher.js
│   │   └── launcher.js
│   ├── utils/
│   │   ├── logger.js
│   │   ├── errors.js
│   │   ├── globalErrorHandler.js
│   │   └── firstRun.js
│   └── constants.js
├── docs/
├── tests/
└── README.md

Configuration

.sesy.json controls how the local window is launched and how long the CLI waits.

| Field | Type | Default | Description | |---|---|---|---| | port | number | 8000 | forwarded renderer port | | framework | string | "electron" | current framework selector | | windowWidth | number | 1280 | local BrowserWindow width | | windowHeight | number | 800 | local BrowserWindow height | | pollIntervalMs | number | 500 | port polling interval | | pollTimeoutMs | number | 60000 | give-up timeout | | electronArgs | array | [] | extra Electron launch args | | env | object | {} | extra Electron environment variables |

Example:

{
  "port": 8000,
  "windowWidth": 1440,
  "windowHeight": 900,
  "pollIntervalMs": 500,
  "pollTimeoutMs": 60000,
  "electronArgs": [],
  "env": {}
}

For apps like dark Studio that need their own local Electron main/preload process, use project mode instead of the default bridge window:

{
  "port": 5173,
  "launchMode": "project",
  "projectCwd": "C:/Users/youha/dark-studio",
  "projectEntry": "out/main/index.js",
  "projectUrlEnvVar": "ELECTRON_RENDERER_URL",
  "projectArgs": []
}

In project mode, sesy watch launches the real local Electron app entrypoint and injects the forwarded URL through projectUrlEnvVar.

Where sesy fits with sesy-guard

sesy works best with @xgauravyaduvanshii/sesy-guard:

• @xgauravyaduvanshii/sesy-guard keeps the remote Electron main process alive in SSH
• sesy uses the resulting forwarded port to open the native app locally

flowchart LR
    A[sesy-guard on remote project] --> B[renderer server survives]
    B --> C[SSH forwarding]
    C --> D[sesy CLI]
    D --> E[local Electron window]

Documentation

• Getting started
• How it works
• Configuration
• Watch command
• Init command
• Status command
• Doctor command
• Troubleshooting
• Multiple projects
• Custom Electron

Local development

npm install
npm test
node bin/sesy.js --help

Troubleshooting

If the forwarded port never comes up, the window stays blank, or Electron cannot be found, start with docs/troubleshooting.md.

License

MIT