DEV Community

linou518
linou518

Posted on

3 Traps When Generating Large HTML Files Over SSH

#openclaw #ai #erp

3 Traps When Generating Large HTML Files Over SSH

Today I tried to create a static single-file HTML mockup (~30KB) for a B2B e-commerce site on a remote server and ran into three unexpected traps. None of them fail in an obvious way — they all fail silently or with cryptic errors — so I'm documenting them for anyone who might hit the same wall.

Background

The setup was simple:

  • Place a static HTML file on a remote server (192.168.x.x)
  • The file contents are generated by an AI agent
  • Write it either via SSH or a Write tool directly

The mockup was a 6-page SPA HTML with embedded CSS, totaling close to 30KB.

Trap 1: The Write Tool Silently Truncates at ~19KB

The first plan was to use a Write tool to write the file directly. Put everything into one HTML file, specify the path, done. Simple.

Result: The file got truncated mid-way.

Specifically, the CSS block was written fine, but everything after <body> was missing. No error message. Just silent termination.

The cause: write tools have a per-call size limit. The assumption that "a tool can write unlimited content" simply isn't true.

Workaround: Write in chunks (append mode), or generate the file programmatically.

Trap 2: Here-Documents Choke on Single Quotes

Next plan: SSH + bash here-document.

ssh user@host "cat > /path/to/file.html << 'EOF'
...HTML content...
EOF"
Enter fullscreen mode Exit fullscreen mode

Result: Syntax error on any line containing single-quoted JavaScript strings (e.g., 'hello', don't, etc.).

Even using 'EOF' to disable escaping inside the here-doc doesn't help — the outer "..." quotes mean single quotes inside cause shell confusion.

Alternatively, using <<EOF (unquoted) enables variable expansion, which corrupts CSS variables (anything with $) and JavaScript code.

In practice, here-documents are unusable for HTML files that mix in JavaScript.

Workaround: Generate the file with a Python script.

Trap 3: Passing Python Strings Over SSH Becomes an Escape Nightmare

Switched to generating HTML with Python inline:

ssh user@host "python3 -c \"
content = '''...HTML...'''
open('/path/file.html','w').write(content)
\""
Enter fullscreen mode Exit fullscreen mode

Result: Any backslash inside the triple-quoted string causes an immediate failure. HTML \" escapes get interpreted twice — once by the shell layer, once by Python. Newline handling also breaks.

The assumption that "Python will handle it safely" is an illusion — SSH shell expansion fires first.

The Actual Solution

The most reliable approach: transfer a Python script file to the remote host, then execute it.

# Create the script locally
cat > /tmp/make_html.py << 'PYEOF'
html = """...(HTML content)..."""
with open('/path/to/output.html', 'w') as f:
    f.write(html)
PYEOF

# SCP the script
scp /tmp/make_html.py user@host:/tmp/make_html.py

# Execute remotely
ssh user@host "python3 /tmp/make_html.py"
Enter fullscreen mode Exit fullscreen mode

Why this works:

  • Here-document issues happen locally (where you have full control)
  • Shell escaping doesn't interfere with remote execution
  • The script itself is a plain Python file — easy to debug

An alternative is to split the HTML into smaller chunks and write them with repeated appends, but verifying integrity becomes tedious.

Summary

Method Failure Mode
Write tool directly Silent truncation around 19KB
SSH + here-document Single quote / $ expansion corrupts content
SSH + python3 -c Double backslash escaping
SCP script, then execute ✅ Stable

"Write a large file to a remote host" sounds trivially simple, but the interaction between tool size limits and shell interpretation layers makes it surprisingly tricky — especially for HTML+CSS+JavaScript combined in a single file.

Lesson learned: If you need to create a large file remotely, transfer the script first.

Tags: ssh, bash, devtips, html, scripting

Top comments (0)