DEV Community

Cover image for Clawspace: A Browser-Based File Explorer for OpenClaw
Nick Taylor
Nick Taylor Subscriber

Posted on • Originally published at nickyt.co

Clawspace: A Browser-Based File Explorer for OpenClaw

#openclaw #aiagents #selfhosted #devtools

I've been working with OpenClaw for a while now. If you're not familiar, it's a self-hosted personal AI assistant that answers you on the channels you already use: WhatsApp, Telegram, Discord, Slack, iMessage, and a lot more. Local, fast, and always-on. One thing that kept coming up for me personally was the need to inspect and edit workspace files without jumping into an SSH session or opening a terminal. It's my own friction point, but if you're an OpenClaw user I suspect I'm not alone.

So I built Clawspace.

GitHub logo nickytonline / clawspace

Clawspace is a browser-based file explorer/editor for an OpenClaw workspace.

Clawspace

Nano banana lobster at a desk

Clawspace is a browser-based file explorer/editor for an OpenClaw workspace.

It gives you:

  • File and directory browsing
  • Monaco editor for text files
  • Save/revert/copy actions
  • Auto-format on blur (supported file types)
  • Basic hardening for writes (path checks, blocked files, audit log)

Why this exists

OpenClaw users often want a fast, authenticated UI to inspect and edit workspace files without opening SSH/terminal sessions.

Clawspace is designed to run on your LAN, or behind a trusted auth proxy (for example Pomerium + OpenClaw trusted-proxy mode).

Install

git clone https://github.com/nickytonline/clawspace
cd clawspace
npm install
Enter fullscreen mode Exit fullscreen mode

Quick start

npm run build
npm run clawspace:serve
Enter fullscreen mode Exit fullscreen mode

Default port is 6789.

Development

npm run dev
Enter fullscreen mode Exit fullscreen mode

Configuration

Clawspace uses the parent of the app directory as the workspace root by default. If you install it elsewhere, set CLAWSPACE_ROOT to an absolute path.

# .env (see .env.example)
CLAWSPACE_ROOT=/absolute/path/to/workspace
CLAWSPACE_IGNORE=".pnpm,dist,logs"
SHOW_INTERNAL_CLAW_FILES=false
Enter fullscreen mode Exit fullscreen mode

Environment variables

Variable Default Description
CLAWSPACE_ROOT
…
View on GitHub

Clawspace is a browser-based file explorer and editor for an OpenClaw workspace.

Clawspace main page

It runs as a lightweight server, gives you a Monaco editor (the same editor that powers VS Code) for text files, and handles the basics you'd want: browsing directories, saving, reverting, deleting, and copying files, and auto-formatting on blur for supported file types. Internal OpenClaw files like SOUL.md are protected and can't be deleted or modified.

Editing a file in Clawspace

Why not just use SSH?

You could. But if you're already running OpenClaw and you want to make a quick edit to a config file or peek at a log, having a UI that loads in your browser is faster than reaching for a terminal. It also fits nicely into situations where the person using the workspace isn't a developer who wants to context-switch into a shell. I find this super handy on my phone.

For my setup, I run it with Pomerium in front of it. Pomerium is an open core identity-aware proxy that handles the authentication layer, so Clawspace never has to think about it. I actually implemented Trusted Proxy Auth mode in OpenClaw to make this work cleanly. (The hardening guide was written before Trusted Proxy Auth mode existed, so I'm in the process of updating it.)

feat(gateway): add trusted-proxy auth mode #15940

nickytonline avatar
nickytonline posted on

Summary

Adds a new trusted-proxy auth mode that delegates authentication to a reverse proxy (Pomerium, Caddy, nginx + OAuth, etc.). This allows Clawdbot to run behind identity-aware proxies or reverse proxies without requiring token auth in WebSocket payloads.

Closes #1560 Relates to #1710

Changes

Types & Schema

  • Add trusted-proxy to GatewayAuthMode union
  • Add GatewayTrustedProxyConfig type with userHeader, requiredHeaders, allowUsers
  • Update zod schema with validation

Auth Logic

  • Add authorizeTrustedProxy() helper function
  • Update authorizeGatewayConnect() to handle trusted-proxy mode
  • Validate proxy source IP against gateway.trustedProxies
  • Support required headers and user allowlist

Runtime Guards

  • Allow non-loopback bind with trusted-proxy mode
  • Reject trusted-proxy + loopback combination
  • Require trustedProxies to be configured

Security Audit

  • Add critical finding when trusted-proxy auth is enabled
  • Flag missing trustedProxies or userHeader configuration
  • Warn when allowUsers is empty

Tests

  • 10 new auth tests covering all trusted-proxy scenarios
  • 4 new security audit tests

Documentation

  • New doc page: /gateway/trusted-proxy-auth
  • Examples for Pomerium, Caddy, nginx, Traefik
  • Security checklist and troubleshooting guide

Example Config

{
  gateway: {
    bind: "lan",
    trustedProxies: ["10.0.0.1"],
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-pomerium-email"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Screenshots and Recordings

CLI in Action

https://github.com/user-attachments/assets/e500cef8-988c-459e-8e9e-16af8a33dc9e

Overview page when trusted proxy mode is enabled

  1. Removed the Gateway Token field entirely when trusted proxy mode is active
  2. Updated the helper text next to the Connect/Refresh buttons - when in trusted proxy mode it now shows "Authenticated via trusted proxy."

CleanShot 2026-02-14 at 11 31 22@2x

Security Considerations

Per maintainer guidance, this is an explicit opt-in feature with:

  • Strict trust boundary (only accepts headers from configured trustedProxies IPs)
  • No silent fallback (rejects if proxy headers missing)
  • Audit warnings to ensure users understand the security implications
  • Clear documentation about when to use and when NOT to use

Testing

npm test -- src/gateway/auth.test.ts
npm test -- src/security/audit.test.ts
Enter fullscreen mode Exit fullscreen mode

All 20 auth tests and 40 security audit tests pass.

Greptile Overview

Greptile Summary

Adds trusted-proxy authentication mode that delegates authentication to reverse proxies (Pomerium, Caddy, nginx + OAuth). The implementation correctly handles the security boundaries with IP-based trust validation, required header checks, and user allowlists. All auth flows validate that requests originate from configured trustedProxies before trusting proxy headers.

Key changes:

  • Added trusted-proxy to GatewayAuthMode union with comprehensive type definitions and zod validation
  • Implemented authorizeTrustedProxy() helper with multi-layered validation (source IP, required headers, user allowlist)
  • Added runtime guards preventing dangerous configurations (rejects loopback binding, requires trustedProxies config)
  • Implemented CIDR notation support in isTrustedProxyAddress() for flexible subnet matching
  • Added comprehensive security audit checks (critical severity for trusted-proxy mode with detailed remediation)
  • Updated UI to hide token/password fields when trusted-proxy mode is active
  • Extensive test coverage (10 auth tests, 4 audit tests, net.ts CIDR tests, runtime config tests)
  • Well-documented with examples for Pomerium, Caddy, nginx, and Traefik

Security posture: The implementation follows defense-in-depth principles with strict validation at multiple layers. The trusted-proxy auth bypasses rate limiting (returns early at src/gateway/auth.ts:314-332), which is appropriate since the proxy handles auth. All validation happens before processing requests, and failure modes are explicit with clear error reasons.

Confidence Score: 5/5

  • This PR is safe to merge with minimal risk.
  • The implementation demonstrates excellent security engineering with defense-in-depth validation, comprehensive test coverage (20+ tests across auth, net, audit, and runtime config), proper error handling, and clear documentation. The trusted-proxy auth logic correctly validates source IPs before trusting headers, preventing header injection attacks. Runtime guards prevent dangerous misconfigurations. The CIDR implementation has edge case validation. All changes follow the repository's coding standards and include appropriate security audit warnings.
  • No files require special attention. The implementation is production-ready.

Last reviewed commit: a1e1c19

View on GitHub

Getting started

The only real requirement is that Clawspace has access to the root of your OpenClaw workspace. How you get there is up to you: npm scripts or the Docker image both work fine.

Via npm:

git clone https://github.com/nickytonline/clawspace
cd clawspace
npm install
npm run build
npm run clawspace:serve
Enter fullscreen mode Exit fullscreen mode

Default port is 6789.

Or via Docker, mounting your workspace volume:

clawspace:
  image: ghcr.io/nickytonline/clawspace:latest
  environment:
    CLAWSPACE_ROOT: /claw/workspace
    CLAWSPACE_IGNORE: ".pnpm,dist,logs"
    SHOW_INTERNAL_CLAW_FILES: "false"
  volumes:
    - ./openclaw-data/workspace:/claw/workspace
  ports:
    - "6789:6789"
Enter fullscreen mode Exit fullscreen mode

I currently run Clawspace inside my workspace rather than as a separate container, mostly because it lets me iterate on it in real time while pairing with OpenClaw. Since it's built with Astro, running npm run dev gives you instant updates via Vite, so I can make changes and see them immediately without an editor, just me and OpenClaw going back and forth. For most people though, the container approach is probably cleaner.

Configuration

By default, Clawspace uses the parent of the app directory as the workspace root. You can override that with an environment variable.

# .env (see .env.example)
CLAWSPACE_ROOT=/absolute/path/to/workspace
CLAWSPACE_IGNORE=".pnpm,dist,logs"
SHOW_INTERNAL_CLAW_FILES=false
Enter fullscreen mode Exit fullscreen mode

The CLAWSPACE_IGNORE variable takes comma-separated patterns, and those get merged with hardcoded defaults (.git, node_modules, etc.), your .gitignore, and a .clawspace-ignore file if you have one at the workspace root.

SHOW_INTERNAL_CLAW_FILES controls whether things like SOUL.md, MEMORY.md, and .env show up in the file browser. Default is false, which is what you want most of the time.

Security

Clawspace assumes network-level auth is handled externally. It's not trying to be a multi-user app with roles and admin checks. File writes are restricted to the workspace root, internal and sensitive files are blocked, and all writes get audited to /claw/workspace/logs/clawspace-edit-audit.log.

If you're exposing it beyond your LAN, put it behind a proxy you trust. I expose mine to the internet using Trusted Proxy Auth mode, with Pomerium as the identity-aware proxy in front of it, so authentication is handled before a request ever reaches Clawspace.

It's meant to be tweaked

Clawspace is intentionally hackable. The README says it plainly: clone it, edit the UI and guardrails, make it yours. It's a starting point for the kind of workspace tooling that fits how you work, not a finished product trying to cover every case.

Fun fact: the look and feel is based on nickyt.co, my personal site. I paired with OpenClaw to build it, which felt like a nice proof of the thing I was building the tool for in the first place.

If you give it a try or have ideas for it, I'd love to hear what you think.

If you want to stay in touch, all my socials are on nickyt.online.

Until the next one!

Top comments (0)

Some comments may only be visible to logged-in visitors. Sign in to view all comments.