Skip to content
Loopstack
Color theme

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 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

Terminal window
npm install @loopstack/remote-file-explorer

Register the module in your app:

import { Module } from '@nestjs/common';
import { RemoteFileExplorerModule } from '@loopstack/remote-file-explorer';


@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 server (@loopstack/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.

Parameter In Type Required Description
workspaceId path string yes The workspace ID
path query string no Base path to list (defaults to the workspace root)

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.

Parameter In Type Required Description
workspaceId path string yes The workspace ID
path query string yes File path to read

Response: FileReadResponse

interface FileReadResponse {
  content: string;
}

Configuration

RemoteFileExplorerModule.forFeature() accepts an optional config object:

Option Type Default Description
enabled boolean true Whether the feature is active
environments string[] all Restrict to specific environment names

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

Package Role
@loopstack/common Shared utilities, CurrentUser decorator
@loopstack/remote-client RemoteClient service and EnvironmentService
@nestjs/common NestJS framework
@nestjs/typeorm TypeORM integration
typeorm ORM

About

Author: Jakob Klippel

License: MIT