Web Terminal and File Explorer in a Self-Hosted PaaS

The Tokyo Night colour theme was a deliberate choice. It is a popular dark theme in the developer community, and it matches sh0's dark mode palette. The 5,000-line scrollback buffer lets you scroll through output without losing history, while keeping memory bounded.

The ResizeObserver on the terminal element ensures that when the browser window resizes or the user adjusts a split pane, the terminal reflows its columns and rows. Without this, lines would wrap incorrectly or columns would render beyond the visible area.

File Explorer: Architecture

The file explorer is more complex than the terminal because it involves multiple operations: browsing, creating, editing, and deleting. Each operation runs via docker exec commands on the target container.

Backend: File Operations

The backend in crates/sh0-api/src/handlers/storage.rs exposes six endpoints for file operations:

GET  /apps/:id/browse?path=/&container=<id>    # List directory
GET  /apps/:id/files/read?path=/etc/nginx.conf # Read file contents
POST /apps/:id/files/write                     # Write file contents
POST /apps/:id/files/mkdir                     # Create directory
POST /apps/:id/files/new                       # Create empty file
DELETE /apps/:id/files?path=/tmp/debug.log     # Delete file or folder

Every operation is a docker exec command. Browsing runs ls -la. Reading runs cat. Writing pipes content to tee. Creating directories runs mkdir -p. Deletion runs rm -rf with safeguards.

BusyBox Compatibility

The first bug we hit was that ls --time-style=long-iso does not work on Alpine-based containers. Alpine uses BusyBox, which has a different ls implementation. Our parser expected GNU ls output and choked on BusyBox's format.

The fix was a three-level fallback:

async fn list_directory(container_id: &str, path: &str) -> Result<Vec<FileEntry>> {
    // Try GNU ls first
    let output = docker_exec(container_id, &["ls", "-la", "--time-style=long-iso", path]).await;
    if output.is_ok() {
        return parse_gnu_ls(output.unwrap());
    }

// Fallback to BusyBox --full-time let output = docker_exec(container_id, &["ls", "-la", "--full-time", path]).await; if output.is_ok() { return parse_busybox_ls(output.unwrap()); }

// Last resort: plain ls -la let output = docker_exec(container_id, &["ls", "-la", path]).await?; parse_plain_ls(output) } ```

The parser also handles edge cases: symlink targets (stripped from the display name), timezone fields in BusyBox output, and the total line at the top of ls output.

Path Traversal Prevention

Every file operation validates the requested path:

fn validate_path(path: &str) -> Result<()> {
    if path.contains("..") {
        return Err(ApiError::bad_request("Path traversal not allowed"));
    }
    Ok(())
}

Additionally, the delete endpoint blocks deletion of protected system directories:

const PROTECTED_PATHS: &[&str] = &[
    "/bin", "/etc", "/usr", "/lib", "/sbin",
    "/proc", "/sys", "/dev",
];

fn validate_delete_path(path: &str) -> Result<()> { validate_path(path)?; let normalized = path.trim_end_matches('/'); if PROTECTED_PATHS.contains(&normalized) { return Err(ApiError::bad_request("Cannot delete protected system directory")); } Ok(()) } ```

This is defence in depth. The dashboard UI also prevents navigating outside the container's filesystem, but the backend enforces it independently. A malicious API call with path=/../../../etc/passwd is rejected before docker exec ever runs.

Container ID Resolution

A subtle bug emerged when users tried to browse files in a database container. The container selector dropdown showed databases by their service UUID (a 36-character string like a1b2c3d4-e5f6-...), but the browse API expected a Docker container ID (a 12 or 64 character hex string).

The solution was resolve_container_id():

async fn resolve_container_id(app_id: &str, container_ref: &str, db: &DbPool) -> Result<String> {
    // Heuristic: UUIDs are 36 chars with hyphens, Docker IDs are 12/64 hex chars
    if container_ref.len() == 36 && container_ref.contains('-') {
        // Look up the service's Docker container ID from the database
        let service = db.get_service(container_ref).await?;
        // IDOR prevention: verify the service belongs to this app
        if service.app_id != app_id {
            return Err(ApiError::forbidden("Service does not belong to this app"));
        }
        Ok(service.container_id)
    } else {
        // Assume it is already a Docker container ID
        Ok(container_ref.to_string())
    }
}

The IDOR (Insecure Direct Object Reference) check is important. Without it, a user could pass a service UUID from a different app and browse that container's files. The check ensures that the referenced service actually belongs to the app specified in the URL path.

Frontend: The Two-Panel Layout

AppFiles.svelte implements a Docker Desktop-style layout:

Left panel (280px): A recursive directory tree (FileTree.svelte) with a container selector dropdown at the top. Folders expand on click, loading their children lazily from the API. A folder/file icon distinguishes entries at a glance.

Right panel (remaining width): Either a directory listing table (when a folder is selected), a file viewer/editor (when a file is selected), or an empty state.

The toolbar spans the top of the right panel: breadcrumb navigation, New File, New Folder, Delete, and Refresh buttons. The create workflow is inline -- click New File, type a name directly in the directory listing, press Enter. No modal, no dialog.

<!-- FileTree.svelte (simplified) -->
<script lang="ts">
  let { appId, containerId } = $props();
  let root = $state<TreeNode>({ path: '/', children: [], loaded: false });

async function loadChildren(node: TreeNode) { const entries = await filesApi.browse(appId, node.path, containerId); node.children = entries .filter(e => e.isDirectory) .map(e => ({ path: ${node.path}${e.name}/, children: [], loaded: false })); node.loaded = true; }

// Expand uses $effect with untrack to prevent infinite loops $effect(() => { const key = ${appId}-${containerId}; untrack(() => { root = { path: '/', children: [], loaded: false }; loadChildren(root); }); }); ```

The Infinite Effect Loop

The most insidious bug in the file explorer was a Svelte 5 reactivity issue. FileTree.svelte had an $effect that both read and wrote root (a $state variable). When loadChildren() mutated root by setting node.children and node.loaded, Svelte 5 detected a state change and re-triggered the effect, which loaded children again, which mutated state again -- an infinite loop of API calls.

The fix required two changes:

1. untrack() around mutations. All state mutations inside the effect are wrapped in untrack(), telling Svelte "these writes should not trigger a re-run of this effect." 2. $derived session key. Instead of the effect depending on root, it depends on a derived key computed from appId and containerId. This means the effect only re-runs when the container changes, not when the tree expands. 3. Error guard. Setting node.loaded = true on error prevents the effect from retrying a failed load indefinitely.

This is a pattern worth remembering for anyone building tree structures with Svelte 5: effects that mutate their own dependencies need explicit untrack() boundaries.

The Edit Experience

When a file is selected, the right panel shows its contents. For text files, an "Edit" button switches to a textarea with Save and Cancel buttons. For binary files, the component detects non-printable characters and shows a "Binary file -- cannot edit" message instead.

{#if editMode}
  <textarea bind:value={editContent}
            class="w-full h-96 font-mono text-sm bg-[var(--bg-secondary)]
                   text-[var(--text-primary)] p-4 rounded" />
  <div class="flex gap-2 mt-3">
    <Button onclick={saveFile}>{t('files.save')}</Button>
    <Button variant="ghost" onclick={() => editMode = false}>
      {t('files.cancel')}
    </Button>
  </div>
{:else}
  <pre class="p-4 text-sm font-mono overflow-x-auto">{fileContent}</pre>
  <Button onclick={() => { editContent = fileContent; editMode = true; }}>
    {t('files.edit')}
  </Button>
{/if}

The file metadata bar below the toolbar shows permissions (e.g., -rw-r--r--), size (human-readable), and last modified date. This is information developers glance at instinctively -- "is this file writable? How old is it?"

Why This Matters

The web terminal and file explorer are not flashy features. They are pragmatic ones. They eliminate the most common reason a developer SSHs into a server after deploying an app: "I need to look inside the container."

For sh0's target audience -- developers who manage their own servers but do not want to spend their days in Docker CLI -- these features close the gap between "I deployed my app" and "I can fully manage my app." The terminal is the escape hatch for anything the dashboard does not cover. The file explorer is the visual tool for the 80% of file operations that do not need a shell.

Together, they make sh0 feel less like a deployment tool and more like a development environment.

---

Next in the series: Real-Time Logs: WebSocket Streaming from Docker Containers -- how we built log streaming with JWT-authenticated WebSockets, auto-reconnect, and a terminal-style viewer.