Clawbox Media Server & Upload

Lightweight HTTP servers for bidirectional file sharing between an AI agent and users on the local network.

What It Does

• - Media Server (port 18801) — Serves files from a shared directory. Users can browse and download.
• Upload Server (port 18802) — Accepts file uploads via web UI (drag-and-drop) or API. Saves to the same shared directory.
• Same-origin design — Upload page served from upload server to avoid CORS/Safari issues.
• Directory listing — Media server root shows all files with download links.
• Auto-start services — Systemd units for both servers (optional).

All files are stored in ~/projects/shared-media and instantly accessible to the agent.

Quick Start (One-Command)

From your login session (with systemd user bus):

CODEBLOCK0

That's it! The installer:

• - Creates ~/projects/shared-media if needed
• Starts both servers immediately
• Installs systemd service files for auto-start on boot

Access URLs (replace 192.168.68.75 with your host's LAN IP):

• - Upload page: INLINECODE3
• File browser: INLINECODE4

Manual Setup

If you prefer to start manually:

1. Start Media Server (serves files):
CODEBLOCK1

2. Start Upload Server (accepts uploads):
CODEBLOCK2

Both read from/write to ~/projects/shared-media by default.

Usage Patterns

Agent → User (Serving Files)

Agent copies a file to the shared directory:
CODEBLOCK3

Then sends the user a link:
CODEBLOCK4

The user can also browse all files at http://192.168.68.75:18801/.

User → Agent (Uploading Files)

User opens http://192.168.68.75:18802/ in any browser, drags files in. ✅ Done.

Agent sees the files immediately in ~/projects/shared-media/ and can read them.

Combined Workflow

1. 1. User uploads via INLINECODE9
2. Agent reads file from disk (~/projects/shared-media/<filename>)
3. Agent processes/transforms it
4. Agent drops result in same directory
5. User downloads from INLINECODE11

Fully LAN-based, no internet.

Configuration

Ports & Paths

Set as environment variables before starting the servers, or edit the systemd service files.

Systemd Services

Service names:

• - media-server.service — Node.js media server
• INLINECODE20 — Python upload server

Enable auto-start (run once from your login session):
CODEBLOCK5

Start/stop/restart/check status:

systemctl --user start|stop|restart|status media-server.service
systemctl --user start|stop|restart|status upload-server.service

API (Upload Server)

Endpoint: POST /upload (multipart/form-data, field name file)

Request:
CODEBLOCK7

Response (JSON):
CODEBLOCK8

The file is immediately available in the shared directory and via the media server.

Security Notes

⚠️ IMPORTANT: Read Before Deploying

• - No authentication — anyone who can reach the ports can upload/download files. Only use on physically secured, trusted networks. Do NOT expose to the internet without additional authentication/reverse proxy.
• Binding address — By default, servers bind to 0.0.0.0 (all interfaces). To restrict to a specific LAN interface, set BIND_ADDR environment variable to your LAN IP (e.g., 192.168.68.75). Example:

  BIND_ADDR=192.168.68.75 MEDIA_PORT=18801 node server.js
  

• - Firewall recommended — Even on LAN, consider blocking external interfaces (WAN) using a host firewall (ufw, iptables). Allow only your LAN subnet to ports 18801/18802.
• Directory listing — The media server root (:18801/) shows all filenames. This may leak information. If privacy is needed, disable directory listing by modifying server.js or block access via firewall.
• Content Security — The upload page uses inline JavaScript (CSP relaxed). This is acceptable for a local-only service, but be aware.
• Systemd services — If you enable systemd services, they run under your user account. Ensure your user account is secure. Consider using a dedicated low-privilege user for production.

Best Practice: Manual Start for Testing

Before enabling systemd auto-start, run the servers manually to verify behavior:

CODEBLOCK10

Then test upload/download from another device. Once satisfied, run install-all.sh to set up systemd services (with the same BIND_ADDR configured in the service files).

Troubleshooting

"Address already in use" on startup

Or change ports via environment variables.

Upload fails with CORS/Safari errors

Systemd user bus not available

Files & Structure

CODEBLOCK12

All files are self-contained; no external npm/pip dependencies beyond Node.js and Python stdlib.

License

Open source. Feel free to modify and redistribute.