feat(opsserver): add container workspace API and backend execution environment for services

changelog.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 2026-03-18 - 1.21.0 - feat(opsserver)
+add container workspace API and backend execution environment for services
+
+- introduces typed workspace handlers for reading, writing, listing, creating, removing, and executing commands inside service containers
+- adds frontend backend-execution environment integration so the service view can open a workspace against a selected service
+- extends Docker exec lookup to resolve Swarm service container IDs when a direct container ID is unavailable
+
 ## 2026-03-17 - 1.20.0 - feat(ops-dashboard)
 stream user service logs to the ops dashboard and resolve service containers for Docker log streaming
 

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/onebox',
-  version: '1.20.0',
+  version: '1.21.0',
   description: 'Self-hosted container platform with automatic SSL and DNS - a mini Heroku for single servers'
 }

ts/classes/docker.ts

@@ -857,7 +857,23 @@ export class OneboxDockerManager {
     cmd: string[]
   ): Promise<{ stdout: string; stderr: string; exitCode: number }> {
     try {
-      const container = await this.dockerClient!.getContainerById(containerID);
+      let container: any = null;
+      try {
+        container = await this.dockerClient!.getContainerById(containerID);
+      } catch {
+        // Not a direct container ID — try Swarm service lookup
+      }
+
+      if (!container) {
+        const serviceContainerId = await this.getContainerIdForService(containerID);
+        if (serviceContainerId) {
+          try {
+            container = await this.dockerClient!.getContainerById(serviceContainerId);
+          } catch {
+            // Service container also not found
+          }
+        }
+      }
 
       if (!container) {
         throw new Error(`Container not found: ${containerID}`);

ts/opsserver/classes.opsserver.ts

@@ -23,6 +23,7 @@ export class OpsServer {
   public schedulesHandler!: handlers.SchedulesHandler;
   public settingsHandler!: handlers.SettingsHandler;
   public logsHandler!: handlers.LogsHandler;
+  public workspaceHandler!: handlers.WorkspaceHandler;
 
   constructor(oneboxRef: Onebox) {
     this.oneboxRef = oneboxRef;
@@ -63,6 +64,7 @@ export class OpsServer {
     this.schedulesHandler = new handlers.SchedulesHandler(this);
     this.settingsHandler = new handlers.SettingsHandler(this);
     this.logsHandler = new handlers.LogsHandler(this);
+    this.workspaceHandler = new handlers.WorkspaceHandler(this);
 
     logger.success('OpsServer TypedRequest handlers initialized');
   }

ts/opsserver/handlers/index.ts

@@ -11,3 +11,4 @@ export * from './backups.handler.ts';
 export * from './schedules.handler.ts';
 export * from './settings.handler.ts';
 export * from './logs.handler.ts';
+export * from './workspace.handler.ts';

ts/opsserver/handlers/workspace.handler.ts

@@ -0,0 +1,181 @@
+import * as plugins from '../../plugins.ts';
+import { logger } from '../../logging.ts';
+import type { OpsServer } from '../classes.opsserver.ts';
+import * as interfaces from '../../../ts_interfaces/index.ts';
+import { requireValidIdentity } from '../helpers/guards.ts';
+import { getErrorMessage } from '../../utils/error.ts';
+
+export class WorkspaceHandler {
+  public typedrouter = new plugins.typedrequest.TypedRouter();
+
+  constructor(private opsServerRef: OpsServer) {
+    this.opsServerRef.typedrouter.addTypedRouter(this.typedrouter);
+    this.registerHandlers();
+  }
+
+  /**
+   * Resolve a service name to a container ID (handling Swarm service IDs)
+   */
+  private async resolveContainerId(serviceName: string): Promise<string> {
+    const service = this.opsServerRef.oneboxRef.services.getService(serviceName);
+    if (!service || !service.containerID) {
+      throw new plugins.typedrequest.TypedResponseError(`Service not found or has no container: ${serviceName}`);
+    }
+    return service.containerID;
+  }
+
+  private registerHandlers(): void {
+    // Read file from container
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_WorkspaceReadFile>(
+        'workspaceReadFile',
+        async (dataArg) => {
+          await requireValidIdentity(this.opsServerRef.adminHandler, dataArg);
+          const containerId = await this.resolveContainerId(dataArg.serviceName);
+          const result = await this.opsServerRef.oneboxRef.docker.execInContainer(
+            containerId,
+            ['cat', dataArg.path],
+          );
+          if (result.exitCode !== 0) {
+            throw new plugins.typedrequest.TypedResponseError(`Failed to read file: ${result.stderr || 'File not found'}`);
+          }
+          return { content: result.stdout };
+        },
+      ),
+    );
+
+    // Write file to container
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_WorkspaceWriteFile>(
+        'workspaceWriteFile',
+        async (dataArg) => {
+          await requireValidIdentity(this.opsServerRef.adminHandler, dataArg);
+          const containerId = await this.resolveContainerId(dataArg.serviceName);
+          // Use sh -c with printf to write content (handles special characters)
+          const escaped = dataArg.content.replace(/'/g, "'\\''");
+          const result = await this.opsServerRef.oneboxRef.docker.execInContainer(
+            containerId,
+            ['sh', '-c', `printf '%s' '${escaped}' > ${dataArg.path}`],
+          );
+          if (result.exitCode !== 0) {
+            throw new plugins.typedrequest.TypedResponseError(`Failed to write file: ${result.stderr}`);
+          }
+          return {};
+        },
+      ),
+    );
+
+    // Read directory from container
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_WorkspaceReadDir>(
+        'workspaceReadDir',
+        async (dataArg) => {
+          await requireValidIdentity(this.opsServerRef.adminHandler, dataArg);
+          const containerId = await this.resolveContainerId(dataArg.serviceName);
+          // Use ls with -1 -F to get entries with type indicators (/ for dirs)
+          const result = await this.opsServerRef.oneboxRef.docker.execInContainer(
+            containerId,
+            ['ls', '-1', '-F', dataArg.path],
+          );
+          if (result.exitCode !== 0) {
+            throw new plugins.typedrequest.TypedResponseError(`Failed to read directory: ${result.stderr}`);
+          }
+          const entries = result.stdout
+            .split('\n')
+            .filter((line) => line.trim())
+            .map((line) => {
+              const isDir = line.endsWith('/');
+              const name = isDir ? line.slice(0, -1) : line.replace(/[*@=|]$/, '');
+              const basePath = dataArg.path.endsWith('/') ? dataArg.path : dataArg.path + '/';
+              return {
+                type: (isDir ? 'directory' : 'file') as 'file' | 'directory',
+                name,
+                path: basePath + name,
+              };
+            });
+          return { entries };
+        },
+      ),
+    );
+
+    // Create directory in container
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_WorkspaceMkdir>(
+        'workspaceMkdir',
+        async (dataArg) => {
+          await requireValidIdentity(this.opsServerRef.adminHandler, dataArg);
+          const containerId = await this.resolveContainerId(dataArg.serviceName);
+          const result = await this.opsServerRef.oneboxRef.docker.execInContainer(
+            containerId,
+            ['mkdir', '-p', dataArg.path],
+          );
+          if (result.exitCode !== 0) {
+            throw new plugins.typedrequest.TypedResponseError(`Failed to create directory: ${result.stderr}`);
+          }
+          return {};
+        },
+      ),
+    );
+
+    // Remove file/directory from container
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_WorkspaceRm>(
+        'workspaceRm',
+        async (dataArg) => {
+          await requireValidIdentity(this.opsServerRef.adminHandler, dataArg);
+          const containerId = await this.resolveContainerId(dataArg.serviceName);
+          const args = dataArg.recursive ? ['rm', '-rf', dataArg.path] : ['rm', '-f', dataArg.path];
+          const result = await this.opsServerRef.oneboxRef.docker.execInContainer(
+            containerId,
+            args,
+          );
+          if (result.exitCode !== 0) {
+            throw new plugins.typedrequest.TypedResponseError(`Failed to remove: ${result.stderr}`);
+          }
+          return {};
+        },
+      ),
+    );
+
+    // Check if path exists in container
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_WorkspaceExists>(
+        'workspaceExists',
+        async (dataArg) => {
+          await requireValidIdentity(this.opsServerRef.adminHandler, dataArg);
+          const containerId = await this.resolveContainerId(dataArg.serviceName);
+          const result = await this.opsServerRef.oneboxRef.docker.execInContainer(
+            containerId,
+            ['test', '-e', dataArg.path],
+          );
+          return { exists: result.exitCode === 0 };
+        },
+      ),
+    );
+
+    // Execute a command in the container (non-interactive)
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_WorkspaceExec>(
+        'workspaceExec',
+        async (dataArg) => {
+          await requireValidIdentity(this.opsServerRef.adminHandler, dataArg);
+          const containerId = await this.resolveContainerId(dataArg.serviceName);
+          const cmd = dataArg.args
+            ? [dataArg.command, ...dataArg.args]
+            : [dataArg.command];
+          const result = await this.opsServerRef.oneboxRef.docker.execInContainer(
+            containerId,
+            cmd,
+          );
+          return {
+            stdout: result.stdout,
+            stderr: result.stderr,
+            exitCode: result.exitCode,
+          };
+        },
+      ),
+    );
+
+    logger.info('Workspace handler registered');
+  }
+}

ts_interfaces/requests/index.ts

@@ -11,3 +11,4 @@ export * from './backups.ts';
 export * from './backup-schedules.ts';
 export * from './settings.ts';
 export * from './logs.ts';
+export * from './workspace.ts';

ts_interfaces/requests/workspace.ts

@@ -0,0 +1,106 @@
+import * as plugins from '../plugins.ts';
+import * as data from '../data/index.ts';
+
+export interface IReq_WorkspaceReadFile extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_WorkspaceReadFile
+> {
+  method: 'workspaceReadFile';
+  request: {
+    identity: data.IIdentity;
+    serviceName: string;
+    path: string;
+  };
+  response: {
+    content: string;
+  };
+}
+
+export interface IReq_WorkspaceWriteFile extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_WorkspaceWriteFile
+> {
+  method: 'workspaceWriteFile';
+  request: {
+    identity: data.IIdentity;
+    serviceName: string;
+    path: string;
+    content: string;
+  };
+  response: {};
+}
+
+export interface IReq_WorkspaceReadDir extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_WorkspaceReadDir
+> {
+  method: 'workspaceReadDir';
+  request: {
+    identity: data.IIdentity;
+    serviceName: string;
+    path: string;
+  };
+  response: {
+    entries: Array<{ type: 'file' | 'directory'; name: string; path: string }>;
+  };
+}
+
+export interface IReq_WorkspaceMkdir extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_WorkspaceMkdir
+> {
+  method: 'workspaceMkdir';
+  request: {
+    identity: data.IIdentity;
+    serviceName: string;
+    path: string;
+  };
+  response: {};
+}
+
+export interface IReq_WorkspaceRm extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_WorkspaceRm
+> {
+  method: 'workspaceRm';
+  request: {
+    identity: data.IIdentity;
+    serviceName: string;
+    path: string;
+    recursive?: boolean;
+  };
+  response: {};
+}
+
+export interface IReq_WorkspaceExists extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_WorkspaceExists
+> {
+  method: 'workspaceExists';
+  request: {
+    identity: data.IIdentity;
+    serviceName: string;
+    path: string;
+  };
+  response: {
+    exists: boolean;
+  };
+}
+
+export interface IReq_WorkspaceExec extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_WorkspaceExec
+> {
+  method: 'workspaceExec';
+  request: {
+    identity: data.IIdentity;
+    serviceName: string;
+    command: string;
+    args?: string[];
+  };
+  response: {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+  };
+}

ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/onebox',
-  version: '1.20.0',
+  version: '1.21.0',
   description: 'Self-hosted container platform with automatic SSL and DNS - a mini Heroku for single servers'
 }

ts_web/elements/ob-view-services.ts

@@ -2,6 +2,7 @@ import * as plugins from '../plugins.js';
 import * as shared from './shared/index.js';
 import * as appstate from '../appstate.js';
 import * as interfaces from '../../ts_interfaces/index.js';
+import { BackendExecutionEnvironment } from '../environments/backend-environment.js';
 import {
   DeesElement,
   customElement,
@@ -135,6 +136,9 @@ export class ObViewServices extends DeesElement {
   @state()
   accessor selectedPlatformType: string = '';
 
+  @state()
+  accessor workspaceOpen: boolean = false;
+
   constructor() {
     super();
 
@@ -186,6 +190,18 @@ export class ObViewServices extends DeesElement {
         width: 16px;
         height: 16px;
       }
+
+      :host(.workspace-mode) {
+        max-width: none;
+        padding: 0;
+        height: 100%;
+        display: flex;
+        flex-direction: column;
+      }
+
+      :host(.workspace-mode) ob-sectionheading {
+        display: none;
+      }
     `,
   ];
 
@@ -347,6 +363,28 @@ export class ObViewServices extends DeesElement {
           this.currentView = 'list';
         }}
         @service-action=${(e: CustomEvent) => this.handleServiceAction(e)}
+        @request-workspace=${async (e: CustomEvent) => {
+          const name = e.detail?.service?.name || this.selectedServiceName;
+          const identity = appstate.loginStatePart.getState().identity;
+          if (!name || !identity) return;
+          try {
+            const env = new BackendExecutionEnvironment(name, identity);
+            await env.init();
+            const detailView = this.shadowRoot?.querySelector('sz-service-detail-view') as any;
+            if (detailView) {
+              detailView.workspaceEnvironment = env;
+            }
+            this.workspaceOpen = true;
+            this.classList.add('workspace-mode');
+          } catch (err) {
+            console.error('Failed to open workspace:', err);
+          }
+        }}
+        @back=${() => {
+          this.workspaceOpen = false;
+          this.classList.remove('workspace-mode');
+          this.currentView = 'list';
+        }}
       ></sz-service-detail-view>
     `;
   }

ts_web/environments/backend-environment.ts

@@ -0,0 +1,155 @@
+/**
+ * BackendExecutionEnvironment — implements IExecutionEnvironment
+ * by routing all filesystem and process operations through the onebox API
+ * to Docker exec on the target container.
+ */
+
+import * as plugins from '../plugins.js';
+import * as interfaces from '../../ts_interfaces/index.js';
+
+// Import IExecutionEnvironment type from dees-catalog
+type IExecutionEnvironment = import('@design.estate/dees-catalog').IExecutionEnvironment;
+type IFileEntry = import('@design.estate/dees-catalog').IFileEntry;
+type IFileWatcher = import('@design.estate/dees-catalog').IFileWatcher;
+type IProcessHandle = import('@design.estate/dees-catalog').IProcessHandle;
+
+const domtools = plugins.deesElement.domtools;
+
+export class BackendExecutionEnvironment implements IExecutionEnvironment {
+  readonly type = 'backend' as const;
+  private _ready = false;
+  private identity: interfaces.data.IIdentity;
+
+  constructor(
+    private serviceName: string,
+    identity: interfaces.data.IIdentity,
+  ) {
+    this.identity = identity;
+  }
+
+  get ready(): boolean {
+    return this._ready;
+  }
+
+  async init(): Promise<void> {
+    // Verify the container is accessible by checking if root exists
+    const result = await this.fireRequest<interfaces.requests.IReq_WorkspaceExists>(
+      'workspaceExists',
+      { path: '/' },
+    );
+    if (!result.exists) {
+      throw new Error(`Cannot access container filesystem for service: ${this.serviceName}`);
+    }
+    this._ready = true;
+  }
+
+  async destroy(): Promise<void> {
+    this._ready = false;
+  }
+
+  async readFile(path: string): Promise<string> {
+    const result = await this.fireRequest<interfaces.requests.IReq_WorkspaceReadFile>(
+      'workspaceReadFile',
+      { path },
+    );
+    return result.content;
+  }
+
+  async writeFile(path: string, contents: string): Promise<void> {
+    await this.fireRequest<interfaces.requests.IReq_WorkspaceWriteFile>(
+      'workspaceWriteFile',
+      { path, content: contents },
+    );
+  }
+
+  async readDir(path: string): Promise<IFileEntry[]> {
+    const result = await this.fireRequest<interfaces.requests.IReq_WorkspaceReadDir>(
+      'workspaceReadDir',
+      { path },
+    );
+    return result.entries;
+  }
+
+  async mkdir(path: string): Promise<void> {
+    await this.fireRequest<interfaces.requests.IReq_WorkspaceMkdir>(
+      'workspaceMkdir',
+      { path },
+    );
+  }
+
+  async rm(path: string, options?: { recursive?: boolean }): Promise<void> {
+    await this.fireRequest<interfaces.requests.IReq_WorkspaceRm>(
+      'workspaceRm',
+      { path, recursive: options?.recursive },
+    );
+  }
+
+  async exists(path: string): Promise<boolean> {
+    const result = await this.fireRequest<interfaces.requests.IReq_WorkspaceExists>(
+      'workspaceExists',
+      { path },
+    );
+    return result.exists;
+  }
+
+  watch(
+    _path: string,
+    _callback: (event: 'rename' | 'change', filename: string | null) => void,
+    _options?: { recursive?: boolean },
+  ): IFileWatcher {
+    // Polling-based file watching — check for changes periodically
+    // For now, return a no-op watcher. Full implementation would poll readDir.
+    return { stop: () => {} };
+  }
+
+  async spawn(command: string, args?: string[]): Promise<IProcessHandle> {
+    // For interactive shell: execute the command via the workspace exec API
+    // and return a process handle that bridges stdin/stdout
+    const cmd = args ? [command, ...args] : [command];
+    const fullCommand = cmd.join(' ');
+
+    // Use a non-interactive exec for now — full interactive shell would need
+    // TypedSocket bidirectional streaming (to be implemented)
+    const result = await this.fireRequest<interfaces.requests.IReq_WorkspaceExec>(
+      'workspaceExec',
+      { command: cmd[0], args: cmd.slice(1) },
+    );
+
+    // Create a ReadableStream from the exec output
+    const output = new ReadableStream<string>({
+      start(controller) {
+        if (result.stdout) controller.enqueue(result.stdout);
+        if (result.stderr) controller.enqueue(result.stderr);
+        controller.close();
+      },
+    });
+
+    // Create a writable stream (no-op for non-interactive)
+    const inputStream = new WritableStream<string>();
+
+    return {
+      output,
+      input: inputStream,
+      exit: Promise.resolve(result.exitCode),
+      kill: () => {},
+    };
+  }
+
+  /**
+   * Helper to fire TypedRequests to the workspace API
+   */
+  private async fireRequest<T extends { method: string; request: any; response: any }>(
+    method: string,
+    data: Omit<T['request'], 'identity' | 'serviceName'>,
+  ): Promise<T['response']> {
+    const typedRequest = new domtools.plugins.typedrequest.TypedRequest<T>(
+      '/typedrequest',
+      method,
+    );
+    return await typedRequest.fire({
+      identity: this.identity,
+      serviceName: this.serviceName,
+      ...data,
+    } as T['request']);
+  }
+}