Skip to content

feat: open projects directly over SSH#623

Open
Paduce wants to merge 3 commits into
inkeep:mainfrom
Paduce:agent/remote-projects
Open

feat: open projects directly over SSH#623
Paduce wants to merge 3 commits into
inkeep:mainfrom
Paduce:agent/remote-projects

Conversation

@Paduce

@Paduce Paduce commented Jul 14, 2026

Copy link
Copy Markdown

What & why

Closes #622.

Remote OpenKnowledge projects previously required starting the web editor on the SSH machine and maintaining a tunnel by hand. This adds a first-class Open over SSH workflow to the desktop app so a project on another machine behaves like a local project.

The change adds:

  • Saved, credential-free SSH machines with add/remove/test controls, a picker that opens to the saved-machine list, remote folder browsing, remote recents, and clear machine/path identity in editor surfaces.
  • A content-addressed companion bundled with Desktop and installed atomically under the SSH user's ~/.ok/remote directory. It needs no global ok installation, sudo, stored password/private key, or PATH change.
  • One exclusive remote server and loopback-only SSH tunnel per editor window, plus remote terminal support, reconnect ownership, and deterministic server/tunnel/PTY teardown.
  • Strict IPC and framed companion protocols, sender/navigation trust boundaries, helper hash/owner/mode validation, canonical path confinement, and HOME-bounded project discovery.
  • A native confirmation that names the selected remote folder and files before initialization. Existing project configuration is preserved.
  • README guidance and a patch changeset. There are no dependency or bun.lock changes.

Remote hosts currently require macOS or Linux, a POSIX-compatible login shell, Node.js 24+, and Git 2.31+.

How this was verified

  • bun run check completed lint, all builds and typechecks, and the changed feature suites. It reaches the known origin/main defect in packages/desktop/tests/unit/verify-native-config-driver.test.mjs, which imports the absent scripts/verify-native-config-in-packaged-dmg.mjs; the desktop package otherwise reports 2,454 passing tests. The same missing-driver failure reproduces without this branch.
  • bun test packages/cli/src/remote-project-bootstrap.test.ts — 17 passed, including HOME-boundary, nested .ok/frontmatter.yml, symlink, and content-confinement cases.
  • bun run --cwd packages/cli typecheck
  • bun run --cwd packages/cli build
  • bun run --cwd packages/desktop build:mac:unsigned
  • Installed the unsigned app locally and exercised a real SSH host end to end: opened the saved-host list, installed and hash-verified the private 0600 companion, tested the connection, browsed to an uninitialized folder, confirmed initialization, created and persisted a document, ran pwd in the remote terminal, and closed the editor. Closing reaped the remote server, local tunnel, and terminal process; the temporary project was then removed.
  • Completed a deep security review of the full diff against origin/main; the final sealed snapshot has zero findings.

Checklist

  • Ran bun run check (lint, typecheck, tests) locally — run in full; blocked only by the pre-existing missing packaged-DMG verification driver described above
  • Added a changeset (bun run changeset) if this changes behavior
  • Updated docs if this changes a user-facing surface
  • I have read CONTRIBUTING.md and agree to license my contribution under the project's terms (CLA)

After you open this PR

  • A maintainer will review your PR. If you don't hear back within a few business days, a comment to nudge is welcome.
  • When your change is accepted, this PR closes automatically — that's how it merges, and your authorship is preserved.

See CONTRIBUTING.md for details.

@CLAassistant

Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

@Paduce Paduce marked this pull request as ready for review July 14, 2026 11:40
@Paduce Paduce requested a deployment to inkeep-oss-sync July 14, 2026 14:17 — with GitHub Actions Waiting
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: Open projects directly over SSH

2 participants