Influxx WSL and Remote Development: SSH Hosts and Windows Notes
Influxx is built so agentic engineering is not trapped on a single laptop folder. You can attach remote SSH hosts, run workspaces on more powerful machines, keep Windows projects on WSL when a Windows runtime is available, and still use the same cockpit for files, terminals, Git, worktrees, and agents. This guide covers SSH remote hosts, remote coding patterns, WSL as a project runtime (Windows notes), how remotes pair with git and task integrations, and how the CLI talks to a running app across those environments — with an honest note that the public desktop installer track today is macOS Apple Silicon first.
Use this article when you need agents on a beefy box, a Linux toolchain under Windows, or a consistent remote workflow that still feels like local Influxx. Related topics — worktrees, agents, notes, browser Design Mode, Computer Use, and privacy — sit alongside these surfaces in product Notes and the ETAPX help center. Stick to shipped behavior: remote execution stays on machines you configure; primary work is local-first unless you deliberately point a project at SSH or WSL.
Point Influxx at a remote host and run agents there with the same cockpit UI — more cores, same workflow.
Platform honesty: macOS-first shipping, WSL as Windows notes
Influxx desktop currently ships for macOS Apple Silicon only (bundle id ai.etapx.influxx) via the notarized DMG and Homebrew casks. That is the supported public install path for day-one desktop use. Product documentation and onboarding still describe Windows-oriented steps — default terminal shell, right-click behavior, and WSL project runtimes — because the cockpit model includes those surfaces. Treat WSL guidance in this article as Windows runtime notes for when you are on a Windows host with WSL, not as a claim that a Windows desktop installer ships on the same track as the current Mac build. SSH remotes remain useful from the Mac cockpit today: your laptop runs Influxx; the remote box runs the agents and heavy builds.
At a glance:
- Public desktop today: macOS Apple Silicon (DMG / Homebrew)
- SSH Hosts: Files, terminals, Git, and workspaces on another machine — usable from the Mac cockpit
- WSL (Windows notes): Host vs distro runtime, per-repo overrides, WSL CLI registration
- Ports panel: Forwards and listening ports on SSH repos
- Integrations: Git providers and Linear/Jira task sources that open workspaces from real issues
- CLI: Install on PATH; on Windows + WSL, register the distro PATH so influxx talks to the desktop app
SSH hosts: remote coding without a second IDE
Influxx SSH Hosts are how you keep the cockpit on your desk while code, agents, and terminals run where the hardware lives. Open Settings → Remote Hosts → SSH Hosts to manage machines, or add a remote host from the sidebar when you attach a new machine. When you add a project you can open a local folder, clone a remote URL, import nested multi-repos, or connect an SSH remote host path — the last path is the entry for remote workspaces that feel local in the UI.
On an SSH-backed project, agents run on the remote box with full file editing, Git, terminals, worktree isolation, reconnect after network blips, and port forwards. Relative paths under the worktree (including .influxx/notes and related product files) stay the same as local checkouts; filesystem operations go through the remote connection. The right activity bar includes a Ports panel for SSH repos so you can see and work with forwarded ports without leaving Influxx. Auto-reconnect keeps sessions usable when laptops sleep or networks flap — you resume the same cockpit state instead of rebuilding the environment by hand.
How to attach an SSH host and open a remote project
Open Settings (⌘, on macOS / Ctrl+, on Windows and Linux) and open Remote Hosts → SSH Hosts, or start from the sidebar when attaching a new machine. Add the host with the connection details your environment already uses for SSH access. From Add project, choose a remote host path (or open a repo path on that host) so Influxx tracks it as a project. After import, pick or create a worktree (workspace) the same way you would locally — main checkout for primary work, feature worktrees for isolated parallel agents. Launch agents and terminals in that worktree; they execute on the remote machine while tabs, Source Control, notes, and browser surfaces stay in the single Influxx window.
SSH workflow checklist:
- Register the host: Settings → SSH Hosts or sidebar “add remote host”
- Open a remote path: Add project → connect SSH remote host path / open folder on the host
- Create worktrees: Same New Workspace / worktree create flow as local — isolation is still per checkout
- Run agents on the box: Terminals and CLI agents are worktree-scoped PTYs on the remote runtime
- Use Ports: Right activity bar → Ports for SSH repos (forwards and detected listening ports)
- Expect reconnect: Session recovery after disconnect is part of the SSH host experience
- Keep notes with the tree: Sidebar notes remain files under .influxx/notes on the remote worktree
Remote machines shine when builds, tests, or multi-agent experiments need more cores and memory than your laptop. You still review diffs, annotate lines, commit, push, and open PRs from the same Source Control and PR surfaces. There is no separate “merge worktree” product verb beyond normal Git: ship on the host (GitHub, GitLab, and so on), then delete or archive the workspace in the UI when you are done.
WSL on Windows: host vs distro runtime
On Windows, Influxx lets you choose the default project runtime — Windows host or a WSL distro — and set per-repo runtime overrides when one project should stay native Windows while another must live inside Linux. That matters for toolchains, path conventions, and agent CLIs that expect a Unix environment. WSL CLI registration puts the influxx command on the distro PATH so commands inside WSL talk to the desktop app instead of becoming a disconnected shell tool. Agent status over WSL has dedicated reliability notes in product documentation — treat WSL as a supported runtime path in the product model, with the shipping caveat above for public desktop installers.
How to set up WSL with Influxx (Windows notes)
During first launch on Windows, onboarding includes default terminal shell and related host choices; after install, open Settings and set the default project runtime to Windows host or your preferred WSL distro. For a single repository that should differ from the default, apply a per-repo runtime override. Install or register the CLI from Settings → General / CLI, then use WSL CLI registration so the distro PATH can invoke influxx against the running desktop app. Verify with influxx status (or your platform binary name) from both sides when you troubleshoot connectivity. If agents look “stuck” or status hooks misbehave across the WSL boundary, re-check CLI registration and the product’s WSL reliability notes before rewriting your toolchain.
WSL tips:
- Default runtime: Pick host vs distro once, then override only where needed
- CLI registration: Desktop Install CLI plus WSL distro registration so both environments reach the app
- Projects: Open repos that already live in the distro filesystem when agents must match Linux tooling
- Parity: Worktrees, terminals, browser tabs, and notes still follow the same cockpit layout
- Paths: Know which runtime a repo uses before debugging “file not found” issues across /mnt and distro homes
Git providers and task sources that feed remote work
Remote hosts are most useful when work starts from real tasks. Settings → Integrations covers git providers: GitHub (with the gh CLI heavily used for in-app PRs and issues), GitLab, Bitbucket, Azure DevOps, and Gitea. You can browse PRs and issues in-app, open a worktree from a task, and review without a context switch to a separate web-only workflow. Linear and Jira connect under Task Sources / Integrations — Linear supports API key plus skill install CTAs; Jira connects as a task source for “start workspace from issue” flows.
A practical pattern: pick an issue or PR from the integration surfaces, open or create a worktree (local, WSL, or SSH-backed depending on the project), and launch the agent with a plan note or prompt. Link worktrees to GitHub issues and PRs from Edit Worktree Details when you want the card and metadata to stay aligned with the host. Create PR / MR composers keep GitHub and GitLab review first-class; Checks and PR Checks panels surface CI so you wait on green without leaving the cockpit — or open the PR page in the embedded browser when you want the full host UI.
Integration surface map:
- Git providers: GitHub, GitLab, Bitbucket, Azure DevOps, Gitea — review and open worktrees from tasks
- Linear: Task source with API key setup and skill install entry points
- Jira: Task source for starting workspaces from issues
- Source Control: Diffs, line review notes, commit, push, Create PR/MR
- Checks: CI status in-panel; embedded browser optional for host pages
CLI across local, SSH, and WSL
The Influxx CLI lets agents and scripts drive the same cockpit you use by hand — worktrees, terminals, browser, orchestration, computer use, automations, and more. It talks to a running Influxx app (or a headless serve runtime when you run serve for remote/mobile pairing). Register the CLI from Settings → General / CLI. On Windows + WSL, use WSL CLI registration for the distro PATH. Examples typically use influxx; Linux PATH installs may expose influxx-ide; dev builds use influxx-dev. The command tree is the same.
How to install and verify the CLI
Open Settings → General / CLI and run Install CLI to register a launcher on PATH. On Windows with WSL, complete WSL CLI registration so the distro can reach the desktop app. Verify with influxx status (or influxx-ide / influxx-dev for your install). Useful smoke checks include influxx open --json, influxx status --json, and influxx agent-context --json. From there, worktree, terminal, tab/browser, and computer command groups mirror the UI whether the project root is local or remote.
CLI recipes that pair with remote work:
- Worktrees: worktree list / create / set / rm / ps — create checkouts and launch agents with --agent and --prompt
- Terminals: terminal create, send, read, wait (tui-idle), split, switch, close
- Headless / pairing: serve with mobile-pairing options; environment add with pairing codes for lab machines
- Status: Agent status over OSC hooks (working / idle / needs input), including WSL considerations in product docs
Cockpit layout reminders for remote work
Influxx is one multi-tab cockpit — not a separate notes app and coding app. Left sidebar: notes, projects/worktrees, add project, setup guide. Center: tab strip for terminals, agents, browser, markdown/editor, emulator, PR/issue surfaces. Right activity bar: Explorer, Agents, Source Control, Checks, Ports (SSH), attached worktrees. Status bar: usage meters, connection pills, integration status. Toggle sidebars with ⌘B / Ctrl+B and ⌘L / Ctrl+L; open Settings with ⌘, / Ctrl+,.
Keyboard anchors:
- Create worktree: ⌘N / Ctrl+N (also shift variants where bound)
- Worktree palette: ⌘J (macOS) · Ctrl+Shift+J (Windows/Linux)
- New terminal: ⌘T / Ctrl+T
- New agent tab (macOS default agent): ⌘⌥T
- Source Control: ⌘⇧G / Ctrl+Shift+G
- New browser tab: ⌘⇧B / Ctrl+Shift+B
Trust, reconnect, and troubleshooting
Primary execution is on your machine or your SSH/WSL hosts — not a hidden cloud runner for ordinary agent CLIs. Only attach SSH hosts you administer or are authorized to use; treat remote shells like local ones for secrets. Sidebar notes are ordinary files under .influxx/notes; they leave the device only if you commit, sync, or export them. Remote pairing uses pairing codes; prefer private networks for headless servers. Telemetry remains opt-in under Settings → Privacy.
Troubleshooting quick hits:
- SSH disconnects: Use reconnect behavior; confirm the Ports panel still reflects the services you expect
- WSL cannot see Influxx: Re-run WSL CLI registration and influxx status from inside the distro
- Wrong files / paths: Confirm host vs WSL runtime and whether the repo lives on /mnt or in the distro home
- CLI cannot connect: Start or focus the app with influxx open; confirm Install CLI for your environment
- Mac-first install questions: Use the macOS Apple Silicon DMG or Homebrew cask for the public desktop track today
End-to-end example: remote fix from the Mac cockpit
On macOS, attach an SSH host and open the service repo on that machine. Create a feature worktree from a Linear or GitHub issue. Write a short plan note in Sidebar Notes and Run it with your default agent so the agent works on the remote checkout. Start the dev server in a terminal tab; use Ports and the embedded browser for preview. Annotate remaining diff lines, send notes back to the agent, commit, push, and open the PR from Source Control. Watch Checks go green without leaving the cockpit. If you later work on Windows with WSL, the same worktree and note patterns apply — choose the distro runtime and register the CLI so status and commands stay connected.
Whether the worktree path is on your Mac, inside WSL, or on an SSH host, the cockpit regions and CLI verbs stay consistent — so muscle memory transfers and agents can script the same steps you would click. Configure SSH Hosts when the machine matters; use WSL notes when a Windows Linux toolchain matters; keep the public Mac installer as your day-one desktop path until other desktop channels ship on the same footing.
