Remote Sessions & Access
Relevant source files
The following files were used as context for generating this wiki page:
Remote Sessions & Access allow you to connect Rebase to external environments, such as home servers or remote development machines, to run coding agents. This system enables the execution of agent tasks, file manipulations, and Git operations on a remote host while maintaining a consistent user interface in the local Rebase desktop application.
The feature set includes remote session synchronization, file system browsing, Git worktree management, and authenticated communication between the local client and the HostEngine running on the remote machine.
Architecture and Protocol
The remote access system follows a client-server architecture where the local Rebase app (client) communicates with a HostServer (server) via an RPC protocol. The server manages a HostEngine that interfaces with the local file system and Git repositories of the remote machine.
Core Components
| Component | Description |
|---|---|
HostServer | Provides a JSON-RPC 2.0 over HTTP endpoint for remote commands. |
HostEngine | Orchestrates the execution of commands, session lifecycle, and provider interaction. |
HostStore | Manages persistence for remote projects, sessions, and device authentication tokens. |
RemoteMachine | A data structure defining a remote endpoint, including its ID, name, and connection string (e.g., SSH). |
Sources: src/features/connections/ui/RemoteSession.test.ts:74-79, host/server.test.ts:25-33
Request Flow
The diagram below illustrates the typical flow of an RPC request from the Rebase client to the remote Host Engine.
Remote Session Management
Remote sessions represent active agent conversations occurring on a remote machine. Unlike local sessions, remote sessions are synchronized with the host, allowing multiple clients to access the same state.
Session Synchronization
Rebase uses sessions.sync to retrieve the current state of a session from the host. If a client disconnects, the host continues to process the agent's work. A different client can later recover the session and see the completed turns.
Sources: host/server.test.ts:269-290, src/features/connections/ui/RemoteSession.test.ts:145-147
Session Lifecycle Commands
Remote sessions are controlled through specific RPC methods dispatched to the host.
commands.dispatch: Handles high-level actions likecreate(starting a new session),send(sending a prompt), anddraft(saving an unsent message).sessions.update: Modifies session metadata such as titles or pinned status.sessions.delete: Permanently removes a session and its associated data from the host.
Sources: host/server.test.ts:133-145, host/server.test.ts:151-171
Remote File and Git Operations
The remote access system provides granular control over the remote file system and Git repositories to enable the agent to function effectively.
Path Resolution
Remote paths are identified using a remote:// protocol prefix, which includes the environment ID and the absolute path on the host. The client resolves these references to ensure file links in the transcript correctly open the remote file in a shared tab.
// Example of remote path resolution
const cwd = "remote://env/home/dev/repo";
expect(resolveWorkspacePath("~/notes.md", cwd)).toBe("remote://env/home/dev/notes.md");
Sources: src/shared/lib/paths.test.ts:112-127, src/features/connections/ui/RemoteSession.test.ts:311-320
Git Worktree Management
Rebase supports creating and managing Git worktrees on remote hosts. This allows agents to work on isolated branches without interfering with the main checkout.
git.worktreeCreate: Creates a new working copy for a specific branch.git.worktrees: Lists all active worktrees on the host.autoWorktreeBranch: Automatically renames branches created by the host once an agent generates a relevant title for the task.
Sources: host/server.test.ts:187-210, host/git-worktrees.test.ts:74-95
Security and Authentication
Access to the remote host is protected by a token-based authentication system managed by the HostStore.
Device Authorization
Each client device must be issued a unique token. The HostStore validates the Authorization: Bearer <token> header on every RPC request. If a token is revoked, the server immediately rejects incoming requests with a 401 status code, even if the request body is currently arriving.
Sources: host/server.test.ts:55-56, host/server.test.ts:114-131
Security Constraints
- Environment ID: Every request must include the
environmentId. The server rejects requests if the host identity has changed. - Path Traversal Protection: The
HostEngineprevents reading files outside of authorized project roots. Symlinks that escape the project directory are blocked. - Origin Validation: For browser-based access, the server validates the
Originheader against untrusted sources.
Sources: host/server.test.ts:305-321, host/server.test.ts:348-372
Summary
The Remote Sessions & Access module provides a robust framework for distributed agent development. By offloading agent execution to a HostEngine while maintaining a synchronized state in the local Rebase GUI, users can leverage powerful remote hardware or specialized environments. The system ensures security through device-specific tokens and strict path validation, while the RPC-based protocol enables seamless management of remote Git repositories and file systems.
Sources: README.md:52-54, src/features/connections/ui/RemoteSession.test.ts:1-20