Git.Zone IDE is a remote-first desktop IDE for developers who want code, terminals, Git, language servers, builds, tests, and AI-assisted edits to run on the machine where the project actually lives.

A small local Electron shell handles SSH host selection, runtime staging, local port forwarding, project tabs, and the SmartAgent control surface. The selected SSH host runs an Eclipse Theia browser backend inside the active workspace, bound to 127.0.0.1 and reachable only through the shell-managed SSH tunnel. The result is a native-feeling desktop IDE with remote-machine execution semantics. 🚀

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

What It Does

Git.Zone IDE turns any reachable SSH host into an isolated, browser-based Theia workstation without making the local Electron app responsible for remote filesystem, terminal, Git, or language-server behavior.

Reads and writes standard OpenSSH host entries in ~/.ssh/config, including HostName, User, Port, IdentityFile, ProxyJump, and ForwardAgent.
Uses the system ssh binary instead of a custom SSH stack, so existing agents, hardware keys, bastion hosts, and enterprise SSH config keep working.
Stages a content-addressed ephemeral runtime into /tmp/gitzone-ide-* on the remote host and skips uploads when the cached hash matches.
Bundles the local Node.js binary with the remote Theia payload, so the active ephemeral runtime path does not require remote pnpm.
Maintains a remote project registry in ~/.git.zone/ide/projects.json and opens each registered folder as an isolated Theia backend.
Allocates a remote loopback port per project, starts Theia on 127.0.0.1, opens a local SSH tunnel, and embeds the IDE in an Electron webview.
Keeps Theia settings under ~/.git.zone/ide/theia and workspace preferences under .git.zone/ide/workspace, while still honoring .vscode preferences.
Provides a SmartAgent panel that can inspect files, read directories, run remote commands, and write files inside the active remote project with explicit user permission for mutating or shell actions.

Quick Start

Prerequisites:

pnpm 10.x, matching the workspace packageManager field.
Node.js on the local machine. The Electron launcher uploads this local Node binary for the remote ephemeral runtime.
OpenSSH client and tar locally.
A reachable SSH host with a POSIX shell and tar available remotely.
A desktop display for Electron. On Linux, scripts/run-electron.mjs can use X11, Wayland, or start sway when DRM is available and no display is running.

Install and build the workspace:

pnpm install
pnpm run build
pnpm run build:theia

Launch the desktop shell:

pnpm run start:electron

Run the remote Theia application directly during Theia-focused development:

pnpm run start:remote

Package the Electron shell:

pnpm --filter '@git.zone/ide-electron-shell' run package

Using The IDE

Start the Electron shell with pnpm run start:electron.
Select an existing SSH host or create one in the Hosts sidebar.
Click Connect Host. The shell stages the remote runtime, checks the remote cache, and loads the remote project registry.
Add a project folder such as $HOME/project or /srv/work/project in the dashboard.
Open the project. Git.Zone IDE starts a dedicated Theia backend on the remote host, opens a local tunnel, and shows the project in a tab.
Use Theia normally. File access, terminal commands, SCM, search, tasks, and language servers execute against the remote workspace.
Open the Agent panel when you want SmartAgent help inside the active remote project.

Runtime Flow

Local Electron Shell
  | reads ~/.ssh/config and SSH agent state
  | builds content-addressed remote runtime payload
  | uploads to /tmp/gitzone-ide-<version>-<sha256> when needed
  v
Remote SSH Host
  | stores project registry and Theia settings in ~/.git.zone/ide
  | starts one Theia backend per opened project on 127.0.0.1:<remotePort>
  v
Local SSH Tunnel
  | forwards 127.0.0.1:<localPort> to 127.0.0.1:<remotePort>
  v
Electron WebView
  | renders the remote Theia project tab

The local shell owns connection orchestration. The remote Theia process owns the real development environment.

Workspace Packages

Package	Purpose
`@git.zone/ide-protocol`	Shared typed contracts for SSH targets, remote server manifests, remote sessions, probes, process status, and port forwards.
`@git.zone/ide-ssh`	OpenSSH config parsing, host saving, SSH argument construction, command execution, free-port discovery, SSH tunnels, tar-over-SSH uploads, and remote host probes.
`@git.zone/ide-server-installer`	Safe remote shell command generation for install plans, ephemeral runtime bootstrapping, readiness checks, runtime cache markers, remote port allocation, project registry reads/writes, and path quoting.
`@git.zone/ide-electron-shell`	The desktop launcher, IPC boundary, SSH session manager, runtime stager, project dashboard, tabbed webview host, and SmartAgent runtime.
`@git.zone/ide-remote-theia`	The Theia browser application used as the remote IDE backend. It bundles editor, filesystem, terminal, SCM, tasks, search, VSX registry, preferences, and workspace support.
`@git.zone/ide-extension-remote`	Theia frontend/backend extension that exposes the remote environment command and Git.Zone-specific preference paths.
`@git.zone/ide-extension-product`	Product-level Theia extension for Git.Zone IDE welcome/help integration.

The workspace packages are currently private, but they form clean typed boundaries and can be used from other packages inside this repository.

Programmer API

Parse And Save SSH Hosts

import {
  listConnectableHosts,
  parseSshConfig,
  saveSshHostConfig,
} from '@git.zone/ide-ssh';

const hosts = listConnectableHosts(parseSshConfig(`
Host dev-box
  HostName dev.example.com
  User deploy
  Port 2222
`));

await saveSshHostConfig({
  alias: 'dev-box',
  hostName: 'dev.example.com',
  user: 'deploy',
  identityFile: '~/.ssh/id_ed25519',
});

parseSshConfig() understands comments, quoted values, multi-host blocks, wildcard hosts, IdentityFile, ProxyJump, and ForwardAgent. saveSshHostConfig() upserts a single-host block and refuses to rewrite ambiguous multi-host blocks.

Run Commands And Open Tunnels

import {
  findFreePort,
  runSshCommand,
  startSshTunnel,
} from '@git.zone/ide-ssh';

const target = {
  id: 'dev-box',
  hostAlias: 'dev-box',
  user: 'deploy',
  port: 2222,
};

const result = await runSshCommand(target, 'uname -a', {
  timeoutMs: 30_000,
});

if (result.exitCode !== 0) {
  throw new Error(result.stderr);
}

const localPort = await findFreePort();
const tunnel = startSshTunnel(target, {
  localPort,
  remotePort: 33990,
});

await tunnel.dispose();

The SSH package sets conservative keepalive options, uses BatchMode=yes by default, and resolves SSH agent sockets from the active environment, ~/.ssh/agent.env, or recent /tmp/ssh-* sockets.

Generate Remote Bootstrap Commands

import {
  createRemoteEphemeralBootstrapCommand,
  createRemoteEphemeralReadinessCommand,
  createRemoteProjectUpsertCommand,
} from '@git.zone/ide-server-installer';

const bootstrap = createRemoteEphemeralBootstrapCommand({
  serverVersion: '0.1.0',
  runtimeRoot: '/tmp/gitzone-ide-0.1.0-deadbeef',
  workspacePath: '$HOME/project',
  theiaPort: 33990,
});

const readiness = createRemoteEphemeralReadinessCommand({
  runtimeRoot: '/tmp/gitzone-ide-0.1.0-deadbeef',
  theiaPort: 33990,
});

const addProject = createRemoteProjectUpsertCommand({
  runtimeRoot: '/tmp/gitzone-ide-0.1.0-deadbeef',
  projectPath: '$HOME/project',
  title: 'Project',
});

The installer package returns shell scripts as strings. The Electron shell sends those scripts over runSshCommand(), checks exit codes, and surfaces stderr directly when remote setup fails.

Build Typed Session Descriptors

import type { IRemoteSessionDescriptor } from '@git.zone/ide-protocol';

const session: IRemoteSessionDescriptor = {
  sessionId: 'session-1',
  target: {
    id: 'dev-box',
    hostAlias: 'dev-box',
  },
  workspacePath: '/srv/work/project',
  serverVersion: '0.1.0',
  createdAt: new Date().toISOString(),
  theia: {
    baseUrl: 'http://127.0.0.1:33990',
    localPort: 33990,
    remotePort: 33990,
    status: 'running',
  },
};

The protocol package is deliberately small: it is the stable type vocabulary shared by the Electron shell, SSH helpers, installer helpers, and Theia integration.

SmartAgent Runtime

The Agent panel wires @push.rocks/smartagent and @push.rocks/smartai into the active remote project.

Auth can come from OPENAI_API_KEY, OPENAI_TOKEN, SmartAI auth, OpenCode auth, Codex auth, or the built-in ChatGPT device sign-in flow.
Agent sessions persist locally under ~/.git.zone/ide/agent-sessions, keyed by the remote project context.
Read-only project tools can list directories and read UTF-8 files under the active remote project root.
Mutating and shell tools require an explicit permission response from the user.
Remote file tools reject paths outside the active project root.
Long command output is truncated before it is returned to the model.

Data Locations

Location	Machine	Purpose
`~/.ssh/config`	Local	Standard OpenSSH host entries read and optionally updated by the launcher.
`~/.ssh/agent.env`	Local	Optional SSH agent socket discovery fallback.
`/tmp/gitzone-ide-stage-*`	Local	Temporary staging directory for the runtime payload before upload.
`/tmp/gitzone-ide-*`	Remote	Ephemeral content-addressed Theia runtime cache.
`~/.git.zone/ide/projects.json`	Remote	Project registry for a connected host.
`~/.git.zone/ide/logs/theia-<port>.log`	Remote	Theia backend logs for opened projects.
`~/.git.zone/ide/theia/settings.json`	Remote	Theia user settings written during remote bootstrap.
`.git.zone/ide/workspace`	Remote workspace	Git.Zone-specific Theia workspace preferences.
`~/.git.zone/ide/agent-sessions`	Local	Persisted SmartAgent chat sessions.

Security Model

Git.Zone IDE intentionally keeps the execution boundary simple.

The remote Theia backend binds to 127.0.0.1, not a public interface.
Access to Theia goes through a local SSH tunnel controlled by the Electron shell.
SSH transport is delegated to system OpenSSH, preserving your existing SSH config, agent policy, ProxyJump setup, and hardware key behavior.
Remote project registration validates that the requested project path exists before storing it.
Agent file tools are rooted to the active project directory and reject path traversal outside that root.
Agent shell commands and file writes require user permission before execution.
Runtime uploads are content-addressed and marked with .gitzone-runtime-sha256, so unchanged runtimes are reused instead of copied repeatedly.

Development Commands

Command	What it does
`pnpm run build`	Builds protocol, SSH helpers, installer helpers, Theia extensions, and the Electron shell.
`pnpm run build:theia`	Builds the full remote Theia browser application into `applications/remote-theia/lib`.
`pnpm run start:electron`	Builds the Electron shell and launches the local desktop app.
`pnpm run start:remote`	Starts the Theia application directly.
`pnpm test`	Runs the build and then all `tstest` test files.
`pnpm test:unit`	Runs the `tstest` suite without the preceding workspace build.

Generated output lives in dist_ts/, lib/, and applications/remote-theia/lib/. Source lives in packages/*/ts, applications/electron-shell/ts, and theia-extensions/*/src.

Test Coverage

The current tests cover the core non-UI behavior:

SSH config parsing, connectable host filtering, SSH argument generation, host upsert behavior, and included SSH config files.
Remote install path planning, shell quoting, ephemeral bootstrap scripts, readiness probes, runtime cache markers, port allocation, and project registry commands.
SmartAgent session persistence keyed by remote project context.
Theia configuration paths and avoidance of legacy .theia workspace preference folders.

Run everything with:

pnpm test

Troubleshooting

Symptom	Check
The launcher says no SSH agent socket was found.	Make sure `SSH_AUTH_SOCK` points to a live socket, write one to `~/.ssh/agent.env`, or rely on identity files configured in `~/.ssh/config`.
Electron cannot start on Linux.	Start X11/Wayland, install `sway` for DRM fallback, or run under a virtual display.
Opening a project fails because Theia files are missing.	Run `pnpm run build:theia` before `pnpm run start:electron`.
Remote upload fails.	Confirm the remote host has `tar`, enough `/tmp` space, and accepts non-interactive SSH commands.
A project path cannot be added.	The path must already exist on the remote host.
Agent prompts are disabled.	Configure `OPENAI_API_KEY`, `OPENAI_TOKEN`, SmartAI/OpenCode/Codex auth, or complete the ChatGPT sign-in flow in the Agent panel.

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the LICENSE file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

Git.Zone IDE