# HyperTwist remote development registration plan: JetBrains Gateway 2026.1.2 and Visual Studio 2022

Created on `2026-05-30`.

## Purpose

This note records the concrete registration plan for remote development against
the new VPS at `212.227.13.220`.

It reflects the host state that was verified during the post-cutover sequence.
It is not a generic remote-development checklist.

As of `2026-05-31`, the practical default lane has widened:

- `VS Code Remote-SSH` is the primary day-to-day lane for agent-first work
- `JetBrains Gateway / Rider` remains available when a true remote IDE backend
  is specifically wanted
- `Visual Studio 2022` remains the backup lane

## Current prepared state

The following is already true:

- the preferred remote-development login is the additive `dev` user, not
  `root`
- `dev` is in `sudo` and `docker`, so normal development and container
  operations do not require a root IDE session
- `dev` and `deploy` password logins remain locked; SSH key auth is the live
  login path
- `dev` now has a narrow `NOPASSWD` sudoers rule for package-management
  commands (`apt`, `apt-get`, `apt-cache`, `apt-mark`), so future package
  installs do not require abandoning the remote-development session
- local SSH alias exists:
  - `scriptoriumai-new-dev`
- local JetBrains/Gateway-compatible key path:
  - `C:\ScriptoriumAI\ops\ssh\scriptorium_vps_ed25519`
- local Visual Studio-compatible PEM key path:
  - `C:\ScriptoriumAI\ops\ssh\visualstudio_vps_ecdsa`
- `dev` login was verified with both keys
- SFTP is enabled on the host
- the VPS currently exposes:
  - `12` vCPU
  - `23 GiB` RAM
  - `16 GiB` swap
- the VPS now has the following verified toolchains available for `dev`:
  - `cmake`, `ninja`, `g++`, `clang`, `clangd`, `clang-format`,
    `clang-tidy`, `gdb`, `lldb`, `ccache`
  - `node 22`, `npm 10`, `pnpm`, `yarn`, `bun`
  - `python3`, `pipx`, `uv`
  - `rust`, `cargo`, `rust-analyzer`, `clippy`, `rustfmt`
  - `go 1.22`
  - `.NET SDK 8.0` and `.NET SDK 10.0`
  - `git-lfs`
  - `Java 21`
  - `PowerShell 7`
  - `docker`, `docker compose`, `jq`, `ripgrep`, `fd`, `tmux`, `htop`
- server-side Forgejo push authentication for `/home/dev/src` main repos is now
  wired through SSH instead of HTTPS credential prompts
- `VS Code Remote-SSH` connection was proven against the new VPS
- remote workspace folders were opened successfully in VS Code without needing a
  local source copy

## Current practical primary lane

Because the operator's current workflow is agent-first rather than
editor-first, the practical default is now:

- use `VS Code Remote-SSH` for normal day-to-day remote work
- keep `JetBrains Gateway / Rider` optional
- keep `Visual Studio 2022` as targeted backup access

Reason:

- the critical requirement is remote file access plus remote command execution,
  not local IDE semantic navigation
- VS Code Remote-SSH already proved easy to connect and easy to extend with
  remote-installed extensions
- the heavier build/test/tooling work can still run on the VPS when launched
  from the remote VS Code window

## Why the IDE session should use `dev`, not `root`

This is an operational rule, not a suggestion.

Reasons:

- JetBrains Gateway installs backend files, caches, logs, and indices into the
  remote user profile; that should live under `/home/dev`, not under
  `/root`
- opening repos as `root` would create root-owned files inside the working
  trees and introduce avoidable permission churn
- `dev` already has the practical rights needed for normal work:
  - `sudo`
  - `docker`
- `root` remains available as the recovery and admin anchor, but it should not
  be the day-to-day IDE user

Operational boundary:

- use `dev` for JetBrains Gateway, Rider, terminal development, and Visual
  Studio remote registration
- use `dev` for `VS Code Remote-SSH` sessions as well
- use `dev` for routine `sudo apt ...` package management now that the narrow
  `NOPASSWD` rule exists
- use `root` for broader system administration, certbot, service repair,
  account recovery, and privileged tasks outside that package-management lane

## Canonical remote folder roots

For `VS Code Remote-SSH`, the authoritative open targets are the remote folder
roots, not the solution files.

Current canonical roots:

- `/home/dev/src/VectorShell`
- `/home/dev/src/HyperTwist`
- `/home/dev/src/ScriptoriumAI`
- `/home/dev/src/NyxOS`
- `/home/dev/src/VerticalTension`

Additional optional roots:

- `/home/dev/src/visual_studio_solutions/multi_project`
- `/home/dev/src/Workspaces`

Current notable solution/package entry surfaces:

- `VectorShell`
  - root: `/home/dev/src/VectorShell`
  - solution: `/home/dev/src/VectorShell/VectorShell.sln`
- `HyperTwist`
  - root: `/home/dev/src/HyperTwist`
  - solution: `/home/dev/src/HyperTwist/HyperTwist.sln`
- `ScriptoriumAI`
  - root: `/home/dev/src/ScriptoriumAI`
  - solution: `/home/dev/src/ScriptoriumAI/ScriptoriumAI.sln`
- `NyxOS`
  - root: `/home/dev/src/NyxOS`
  - package root: `/home/dev/src/NyxOS/package.json`
- `VerticalTension`
  - root: `/home/dev/src/VerticalTension`
  - package root: `/home/dev/src/VerticalTension/package.json`
- `multi_project`
  - root: `/home/dev/src/visual_studio_solutions/multi_project`
  - solution: `/home/dev/src/visual_studio_solutions/multi_project/multi_project.sln`

Operational rule:

- do **not** create or convert more repos into `.sln` form merely for
  `VS Code Remote-SSH`
- keep the existing solutions where they already exist
- treat folder roots as the primary open targets in VS Code

## Why JetBrains Gateway is the primary lane

This section remains technically true about the remote IDE backend model, but it
is no longer the default workflow recommendation for the current operator
posture.

JetBrains' current 2026.1 remote-development model is the correct fit for this
VPS.

Relevant product facts:

- Rider remote development is designed for a remote machine that hosts the
  source code and the IDE backend
- the local machine acts as a client
- source code does not need to be stored on the laptop
- Gateway can read connection definitions from `~/.ssh/config`
- the remote host must provide SSH, SFTP, a recent Linux AMD64 environment, and
  a free backend port

This matches the intended posture for this VPS.

Operational consequence for resource pressure:

- the JetBrains backend, indexes, caches, code analysis, language services, and
  most long-lived IDE memory pressure move onto the VPS
- the laptop still renders the client UI and keeps some local memory for the
  frontend, but the heavy backend process is remote
- when builds, package restores, code generation, and terminal work are run
  inside the remote session, that CPU and RAM pressure also stays on the VPS

So yes: JetBrains Gateway is the lane that meaningfully offloads RAM pressure to
the VPS.

But the current practical reading is:

- `JetBrains Gateway / Rider` is the richer remote IDE lane
- `VS Code Remote-SSH` is the simpler practical default for agent-first work

Official references:

- JetBrains Rider remote development overview:
  `https://www.jetbrains.com/help/rider/Remote_development_overview.html`
- JetBrains Gateway connect flow:
  `https://www.jetbrains.com/help/rider/Remote_development-a.html`
- JetBrains Rider remote development prerequisites:
  `https://www.jetbrains.com/help/rider/Prerequisites.html`
- JetBrains Gateway installation:
  `https://www.jetbrains.com/help/rider/JetBrains_Gateway.html`

## Why Visual Studio 2022 is only the backup lane

Visual Studio 2022 remote Linux support is not the same architecture as
JetBrains Gateway.

Current Microsoft-documented behavior:

- for remote Linux C++ targets, Visual Studio copies source to the remote Linux
  system and builds there
- for remote .NET Linux debugging, Visual Studio attaches to a process over SSH
  and expects the relevant local source and symbols flow

That means the local Visual Studio IDE remains the primary frontend and keeps
its own solution state, UI memory, extensions, and language-service load on the
laptop. The remote host is mainly a target for build/debug operations, not the
persistent IDE backend.

So Visual Studio 2022 is useful as:

- a backup Linux C++ connection lane
- a backup remote debugger lane

It is **not** a true thin-client replacement for Gateway, and it is **not** the
best path if the goal is to move most IDE RAM pressure away from the laptop.

## Why VS Code Remote-SSH is viable for the current workflow

For the current operator posture, `VS Code Remote-SSH` is viable because:

- it installs `VS Code Server` on the remote host
- remote terminals, builds, tests, and most workspace-extension work can run on
  the VPS
- the agent window can operate against the remote workspace when the relevant
  extension is installed in the remote SSH target
- the local laptop still keeps the VS Code/Electron UI, but the heavier
  workspace-side execution can move onto the server

Operational boundary:

- this is real offload, but not zero local RAM usage
- if a specific extension is UI-local only, some of its cost remains local
- for the current agent-first workflow, that tradeoff is acceptable and does
  not justify forcing every repo into `.sln` form

Official references:

- VS Code Remote-SSH:
  `https://code.visualstudio.com/docs/remote/ssh`
- VS Code extension host model:
  `https://code.visualstudio.com/api/advanced-topics/extension-host`
- VS Code remote extensions:
  `https://code.visualstudio.com/api/advanced-topics/remote-extensions`
- VS Code Agents window:
  `https://code.visualstudio.com/docs/copilot/agents/agents-window`

Official references:

- Connect to your remote Linux system by using Visual Studio:
  `https://learn.microsoft.com/en-us/cpp/linux/connect-to-your-remote-linux-computer?view=msvc-170`
- Configure a Linux CMake project in Visual Studio:
  `https://learn.microsoft.com/en-us/cpp/linux/cmake-linux-configure?view=msvc-170`
- Configure and build with CMake Presets in Visual Studio:
  `https://learn.microsoft.com/en-us/cpp/build/cmake-presets-vs?view=msvc-150`
- Debug .NET Core on Linux using SSH by attaching to a process:
  `https://learn.microsoft.com/en-us/visualstudio/debugger/remote-debugging-dotnet-core-linux-with-ssh?view=vs-2022`

## Recommended registration order

Do not start with every repo at once.

Recommended order:

1. `VectorShell`
2. `HyperTwist`
3. `ScriptoriumAI`
4. `NyxOS`
5. `VerticalTension`

Reason:

- `VectorShell` is currently the cleanest pilot lane
- `HyperTwist` only has light local IDE churn on the server copy
- `ScriptoriumAI`, `NyxOS`, and `VerticalTension` currently have heavier
  working-tree state on the server and should be opened only after the
  connection path itself is proven

## JetBrains Gateway registration plan

### Phase 1: host preflight

The host preflight is now complete.

1. keep using the `dev` user for IDE sessions
2. leave `root` as recovery/admin only
3. keep the remote source tree under `/home/dev/src`
4. leave the Forgejo push path on the server-side repos on SSH

### Phase 2: local client preflight

1. install JetBrains Gateway directly or use JetBrains Rider `2026.1.2`
2. ensure the `Remote Development Gateway` plugin is enabled
3. use the local SSH alias already prepared:
   - `scriptoriumai-new-dev`

### Phase 3: first registration in Gateway

1. open JetBrains Gateway or Rider -> `Remote Development`
2. choose `SSH`
3. choose `Parse config file ~/.ssh/config` or manually select:
   - host: `212.227.13.220`
   - user: `dev`
   - key: `C:\ScriptoriumAI\ops\ssh\scriptorium_vps_ed25519`
4. click `Check Connection and Continue`
5. select Rider backend version `2026.1.2`
6. keep the backend install path default unless there is a later reason to move
   it:
   - `~/.cache/JetBrains/RemoteDev/dist`
7. before first open, set backend heap explicitly if indexing pressure is high
8. choose the remote project path

Recommended first project:

- `/home/dev/src/VectorShell`

### Phase 4: first validation inside the session

Validate this exact sequence:

1. open integrated terminal
2. run:
   - `whoami`
   - `pwd`
   - `git remote -v`
3. confirm the repo lives under `/home/dev/src/...`
4. confirm `origin` uses SSH to `git.scriptoriumai.io`
5. confirm JetBrains indexing finishes without backend distress
6. edit one disposable file or comment and revert it
7. if the repo is clean enough, perform a `git fetch`

### Phase 5: project expansion

After `VectorShell` proves stable:

1. register `HyperTwist`
2. then register `ScriptoriumAI`
3. then register `NyxOS`
4. then register `VerticalTension`

## VS Code Remote-SSH registration plan

### Phase 1: local client preflight

1. install `Remote - SSH`
2. connect using the prepared host alias:
   - `scriptoriumai-new-dev`
3. if the host is entered manually by IP instead, use:
   - host: `212.227.13.220`
   - user: `dev`
   - key: `C:\ScriptoriumAI\ops\ssh\scriptorium_vps_ed25519`

### Phase 2: first remote window

1. let VS Code install `VS Code Server` on the VPS
2. open the canonical remote folder root:
   - `/home/dev/src/VectorShell`
3. add the other canonical roots to the workspace as needed:
   - `/home/dev/src/HyperTwist`
   - `/home/dev/src/ScriptoriumAI`
   - `/home/dev/src/NyxOS`
   - `/home/dev/src/VerticalTension`

### Phase 3: extension placement rule

1. install agent and development extensions into the remote SSH target when
   they need workspace authority
2. confirm the extension is installed under the remote host target, not only in
   the local VS Code UI

### Phase 4: first offload validation

Validate this exact sequence:

1. open a remote terminal
2. run:
   - `whoami`
   - `pwd`
   - `cd /home/dev/src/VectorShell`
   - `git remote -v`
3. run one safe repo-native command from each active repo when needed
4. confirm the heavy command processes appear on the VPS rather than only on
   the laptop

## Visual Studio 2022 backup registration plan

### Scope boundary

Use this only for:

- Linux C++ remote project work
- remote Linux debugging
- targeted backup access when JetBrains Gateway is unavailable

Do not treat it as a complete replacement for Gateway.

### Phase 1: workload and key

1. ensure Visual Studio Community 2022 has the Linux/C++ remote development
   workload installed
2. use the prepared PEM-compatible key:
   - `C:\ScriptoriumAI\ops\ssh\visualstudio_vps_ecdsa`

### Phase 2: connection registration

1. open `Tools -> Options -> Cross Platform -> Connection Manager`
2. add a new connection
3. enter:
   - host: `212.227.13.220`
   - port: `22`
   - user: `dev`
   - auth type: `Private Key`
   - private key: `C:\ScriptoriumAI\ops\ssh\visualstudio_vps_ecdsa`
4. connect and save

### Phase 3: usage model

For C++ Linux projects:

- open a CMake-based project
- add a Linux target
- let Visual Studio target the remote system through Connection Manager

For .NET remote debugging:

- deploy or run the target process on Linux
- use `Debug -> Attach to Process`
- choose `SSH`
- attach to the running Linux process

### Visual Studio operational caveat

Visual Studio's Linux C++ path copies source to the remote Linux machine for
remote targets. That is acceptable as a backup workflow, but it is not the same
as the Gateway thin-client model.

## Server-side Git auth and remote topology that were changed

The following server-side changes were made to support remote development under
`dev`:

- local SSH alias added:
  - `scriptoriumai-new-dev`
- local Visual Studio-compatible private key added:
  - `C:\ScriptoriumAI\ops\ssh\visualstudio_vps_ecdsa`
- server-side Forgejo SSH key added for `dev`:
  - `/home/dev/.ssh/id_ed25519_forgejo`
- server-side working root seeded under:
  - `/home/dev/src`
- the following server-side repo `origin` remotes were changed from HTTPS to
  SSH:
  - `/home/dev/src/HyperTwist`
  - `/home/dev/src/ScriptoriumAI`
  - `/home/dev/src/VerticalTension`
  - `/home/dev/src/NyxOS`
  - `/home/dev/src/VectorShell`

Authoritative SSH host used by those repos:

- `git@git.scriptoriumai.io:...` on SSH port `2222`

Important boundary:

- these changes were made to the VPS-side working copies under `/home/dev/src`
- this note does **not** assume that every local laptop repo was changed in the
  same way

## Retreat path if development returns to local-first

If the operator later decides to retreat from server-first remote development,
the clean reversal sequence is:

1. pull or mirror any final server-side commits back to the authoritative local
   laptop copies first
2. disable or uninstall the reverse-sync scheduled task if it is no longer
   wanted:
   - `VPS-Remote-Dev-Reverse-Sync`
3. stop using JetBrains Gateway / Visual Studio against the VPS for daily work
4. for each server-side repo that should revert to HTTPS, run on the VPS:
   - `git remote set-url origin https://git.scriptoriumai.io/<owner>/<repo>.git`
5. if server-side SSH push auth is no longer wanted, remove:
   - the `dev-vps-forgejo-212-227-13-220` key entry from the Forgejo account
   - `/home/dev/.ssh/id_ed25519_forgejo`
   - local alias `scriptoriumai-new-dev` from `~/.ssh/config`
   - local key `C:\ScriptoriumAI\ops\ssh\visualstudio_vps_ecdsa` if the Visual
     Studio path is also being retired
6. leave `root` and `dev` accounts intact unless there is an explicit later
   account-hardening operation

Practical note:

- the safest retreat is to switch workflow authority back to the laptop first
  and only then reduce the VPS-side convenience wiring

## SSH stability note

Short transient disconnect/reconnect events can still happen if the underlying
network blips, but the current local SSH posture now includes keepalive
protection for the prepared host entries.

Current local SSH config posture:

- `ServerAliveInterval 30`
- `ServerAliveCountMax 6`
- `TCPKeepAlive yes`

Prepared host entries:

- `scriptoriumai`
- `scriptoriumai-new`
- `scriptoriumai-new-dev`
- direct host entry for `212.227.13.220`

Operational reading:

- prefer connecting through `scriptoriumai-new-dev` so the prepared keepalive
  settings are definitely used
- immediate reconnect after a brief drop is acceptable during stabilization
- if disconnects become persistent rather than momentary, inspect the network
  path before treating the VPS or toolchain as the root cause

## Immediate next clean implementation slice

The next clean slice is no longer provisioning. It is offload validation:

1. close `Rider` if it is no longer needed for this lane
2. validate `VS Code Remote-SSH` offload on `/home/dev/src/VectorShell`
3. validate the same lane on `/home/dev/src/HyperTwist`
4. then widen into `ScriptoriumAI`, `NyxOS`, and `VerticalTension`
