@loopstack/filesystem-examples

Filesystem workflow examples for the Loopstack  automation framework.

Four ways workflows interact with the filesystem in Loopstack: isolated Docker sandboxes, remote workspace browsing, remote command execution, and local file-tree inspection.

Install as Source (Recommended)

npx giget@latest gh:loopstack-ai/loopstack/registry/examples/filesystem-examples src/filesystem-examples

Register the module:

import { Module } from '@nestjs/common';
import { LoopstackModule } from '@loopstack/loopstack-module';
import { FilesystemExamplesModule } from './filesystem-examples/filesystem-examples.module';
 
@Module({
  imports: [LoopstackModule.forRoot(), FilesystemExamplesModule],
})
export class AppModule {}

Install as a Dependency

npm install @loopstack/filesystem-examples

import { FilesystemExamplesModule } from '@loopstack/filesystem-examples';

Required app-module configuration

The Remote File Explorer and Remote Client examples connect to a remote agent. FilesystemExamplesModule declares the slot via RemoteClientModule.forFeature({ slots: [{ type: 'sandbox' }] }), but the consumer must register at least one matching environment in their root module via RemoteClientModule.forRoot(...):

import { Module } from '@nestjs/common';
import { LoopstackModule } from '@loopstack/loopstack-module';
import { RemoteClientModule } from '@loopstack/remote-client';
import { FilesystemExamplesModule } from '@loopstack/filesystem-examples';
 
@Module({
  imports: [
    LoopstackModule.forRoot(),
    RemoteClientModule.forRoot({
      environments: {
        available: [
          {
            type: 'sandbox',
            name: 'Local Remote Server',
            connectionUrl: process.env.SANDBOX_URL ?? 'http://localhost:3080',
            agentUrl: process.env.SANDBOX_AGENT_URL ?? 'http://localhost:3001',
            local: true,
          },
        ],
      },
    }),
    FilesystemExamplesModule,
  ],
})
export class AppModule {}

The type: 'sandbox' must match the slot type declared by FilesystemExamplesModule. Workspaces created in Studio auto-select the environment from the matching type.

The Sandbox and Local File Explorer examples don’t depend on the remote server and work without this config.

Environment

The Sandbox example requires Docker. The Remote File Explorer and Remote Client examples require a running remote agent (the simplest option is @loopstack/remote-server on localhost:3001).

Examples

Sandbox

Walks the complete Docker sandbox lifecycle: sandboxInit → directory + file operations (sandboxCreateDirectory, sandboxWriteFile, sandboxReadFile, sandboxListDirectory, sandboxExists, sandboxFileInfo, sandboxDelete) → sandboxDestroy. Useful for isolated execution of untrusted code.

Files

• sandbox-example.workflow.ts — workflow class

Remote File Explorer

Uses GlobTool and ReadTool from @loopstack/remote-client to find Markdown files in a remote workspace and read the first match.

Files

• remote-file-explorer-example.workflow.ts — workflow class

Remote Client

Demonstrates @loopstack/remote-client beyond file browsing: write a file via WriteTool, run a shell command via BashTool, then read the result with ReadTool. Useful when you need command execution against a remote workspace.

Files

• remote-client-example.workflow.ts — workflow class

Local File Explorer

Demonstrates FileSystemService from @loopstack/local-file-explorer-module — builds a file tree of the workspace root and renders it as markdown. The same module also exposes a REST API for the Studio file panel.

Files

• local-file-explorer-example.workflow.ts — workflow class

About

Author: Jakob Klippel 

License: MIT