@loopstack/remote-file-explorer-module

File browsing module for the Loopstack  automation framework.

Exposes REST endpoints that let a frontend (like Loopstack Studio) browse the file system of a remote workspace. The controller resolves the workspace’s remote agent URL and proxies requests through RemoteClient from @loopstack/remote-client.

When to Use

• You are building a UI that needs to render a file tree and display file contents for a remote workspace.
• You want authenticated REST endpoints that proxy file requests to a remote agent without exposing the agent URL to the client.
• Use @loopstack/local-file-explorer-module instead if the files are on the local machine.
• Use GlobTool / ReadTool from @loopstack/remote-client instead if you need file access inside a workflow (this module provides no workflow tools).

Installation

npm install @loopstack/remote-file-explorer-module

Register the module in your app:

import { Module } from '@nestjs/common';
import { RemoteFileExplorerModule } from '@loopstack/remote-file-explorer-module';
 
@Module({
  imports: [RemoteFileExplorerModule],
})
export class AppModule {}

RemoteFileExplorerModule depends on RemoteClient and EnvironmentService from @loopstack/remote-client, which must be available in the DI container (import RemoteClientModule in a parent module).

Feature gating

Use forFeature() to register the module with optional feature-flag configuration:

RemoteFileExplorerModule.forFeature({ enabled: true, environments: ['production'] });

Quick Start

Once imported, the controller is available at /api/v1/workspaces/:workspaceId/remote-files. No additional setup is required beyond having RemoteClientModule registered.

GET /api/v1/workspaces/:workspaceId/remote-files/tree?path=src
GET /api/v1/workspaces/:workspaceId/remote-files/read?path=src/index.ts

Both endpoints require an authenticated user (resolved via @CurrentUser()).

How It Works

Frontend (Studio)
    |
    |  GET /api/v1/workspaces/:workspaceId/remote-files/tree?path=src
    v
RemoteFileExplorerController
    |
    |  EnvironmentService.getAgentUrlForWorkspace(workspaceId)
    |  -> resolves the remote agent URL for the workspace
    |
    |  RemoteClient.getFileTree(agentUrl, path)
    v
Remote Agent (remote-server)
    |
    |  reads filesystem, returns FileTreeNode[]
    v
Response -> Frontend

The controller has two endpoints:

1. GET tree — calls RemoteClient.getFileTree(). Walks the workspace root when no path query param is provided.
2. GET read — calls RemoteClient.readFile(). Requires a path query param.

Both endpoints resolve the workspace’s agent URL via EnvironmentService.getAgentUrlForWorkspace() before proxying.

Endpoints Reference

GET /api/v1/workspaces/:workspaceId/remote-files/tree

Returns the directory tree for the given path.

Response: FileTreeNode[]

interface FileTreeNode {
  id: string;
  name: string;
  path: string;
  type: 'file' | 'folder';
  children?: FileTreeNode[];
}

GET /api/v1/workspaces/:workspaceId/remote-files/read

Returns the content of a single file.

Response: FileReadResponse

interface FileReadResponse {
  content: string;
}

Configuration

RemoteFileExplorerModule.forFeature() accepts an optional config object:

No environment variables are required by this module itself. The remote agent URL is resolved at runtime by EnvironmentService from @loopstack/remote-client.

Public API

• Module: RemoteFileExplorerModule — NestJS module with forFeature() static method
• Controller: RemoteFileExplorerController — REST controller with getFileTree() and readFile() endpoints

Dependencies

Related

• @loopstack/remote-client — the underlying client this module proxies through; also provides GlobTool, ReadTool, and other workflow tools for remote file operations
• @loopstack/local-file-explorer-module — same concept for local filesystems instead of remote agents
• Remote File Explorer example workflow  — demonstrates using GlobTool and ReadTool from @loopstack/remote-client in a workflow

About

Author: Jakob Klippel 

License: MIT