Problem

When Hermes runs in a sandboxed terminal backend (Docker, SSH, Modal, Singularity), the agent creates files inside the sandbox but has no way to send them to the user. Similarly, when users send file attachments on messaging platforms, those files are not injected into the sandbox.

This is the #1 missing capability for production sandboxed deployments.

What We Already Have

The foundational pieces exist but are not connected:

1. Base64 File Transfer (environments/tool_context.py)

Working upload_file() / download_file() with chunked base64 piping between host and sandbox. Currently only used by RL ToolContext — NOT exposed as an agent tool.

2. MEDIA: Tag System (gateway/platforms/base.py)

Agent includes MEDIA:/path/to/file in response text. BasePlatformAdapter.extract_media() detects these tags and routes files by extension (images → send_image, audio → send_voice, documents → send_document). Only works for host-local files.

3. Platform Send Methods

Platform adapters are the #1 blocker. Even if send_file existed today, files can't be delivered on 3/4 messaging platforms.

Research

Investigated 50+ sources across cloud IDEs, container orchestration, CI/CD artifact systems, AI APIs, notebook environments, novel transfer protocols, and agent codebases.

How Other Agents Handle This

How AI APIs Handle Files

Container File Transfer Patterns

Key Insight: Docker Archive API > Base64

The current base64-over-exec approach is the worst performing option. Docker's Archive API is what docker cp uses internally:

# Download: tar stream, no base64 overhead, handles binary perfectly
bits, stat = container.get_archive("/workspace/report.pdf")

# Upload: accepts tar archive bytes  
container.put_archive("/workspace/", tar_data)

Key Insight: Compression Before Base64

Inspired by the Kitty terminal file transfer protocol: gzip before base64 reduces payload 50-80% for text files. This should be the default for the base64 fallback path.

Messaging Platform File Limits

For files exceeding these limits → upload to temp storage, send download URL.

Proposed Solution

Architecture

┌─────────────────────────────────────────────────────┐
│                   send_file Tool                     │
│  send_file(path, [message])                         │
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│          File Transfer Layer (per-backend)           │
│  Docker:      get_archive API (tar stream)          │
│  SSH:         SCP/SFTP via ControlMaster connection  │
│  Modal:       sb.open() Filesystem API               │
│  Singularity: bind mount or gzip+base64 over exec   │
│  Local:       direct filesystem (no transfer)        │
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│          Delivery Layer (per-frontend)               │
│  CLI:       copy to CWD, print path                 │
│  Telegram:  bot.send_document() (< 50 MB)           │
│  Discord:   discord.File() (< 25 MB)                │
│  Slack:     files_upload_v2() (< 1 GB)              │
│  WhatsApp:  send_document() via bridge              │
│  Fallback:  presigned URL for oversized files       │
└─────────────────────────────────────────────────────┘

The send_file Tool

{
    "name": "send_file",
    "description": "Send a file from the terminal environment to the user. Works across all backends and platforms.",
    "parameters": {
        "path": {
            "type": "string",
            "description": "Path to the file inside the terminal environment"
        },
        "message": {
            "type": "string", 
            "description": "Optional caption/message to send with the file"
        }
    }
}

Flow:

1. Agent calls send_file(path="/workspace/report.pdf")
2. Tool checks file exists + gets size via terminal
3. Local: file already on host, get absolute path
4. Docker: extract via get_archive API (tar stream, no base64)
5. SSH: extract via SCP over existing ControlMaster
6. Modal/Singularity: extract via gzip+base64 over exec
7. Save to ~/.hermes/file_cache/<uuid>_<filename>
8. CLI: copy to user CWD
9. Gateway: return MEDIA:<host_path> → platform sends via send_document()

User Upload → Sandbox (Receive Side)

1. Gateway downloads user's file attachment → ~/.hermes/file_cache/
2. Inject into sandbox via reverse of send_file transport
3. Add context to conversation: [User uploaded: report.csv (42 KB) at /workspace/uploads/report.csv]

Tiered Transfer Strategy

Security

• File cache auto-cleanup (TTL-based, default 1 hour)
• Path traversal validation (realpath + prefix check)
• Configurable max file size (default 50 MB)
• MIME type detection via magic bytes (not extension)
• UUID-based cache filenames (original name in metadata only)
• Content-addressed storage (SHA-256) for dedup + integrity

Implementation Plan

Phase 0: Platform Adapter Gaps (PREREQUISITE) — ~2h

Fix the #1 blocker. Add missing methods to platform adapters:

Files to modify:

• gateway/platforms/telegram.py — Add send_document() via bot.send_document()
• gateway/platforms/discord.py — Add send_document() via discord.File()
• gateway/platforms/slack.py — Add send_document() via files_upload_v2()
• Add send_image_file() and send_video() overrides to all three

Phase 1: send_file Tool (MVP) — ~4h

Files to create:

• tools/send_file_tool.py (~150 lines) — The tool itself

Files to modify:

• tools/environments/base.py — Add download_file() to BaseEnvironment
• tools/environments/docker.py — Implement via Docker Archive API
• tools/environments/ssh.py — Implement via SCP/SFTP
• model_tools.py — Register the new tool
• toolsets.py — Add to appropriate toolsets (file toolset)

Phase 2: User Upload → Sandbox — ~4h

Files to modify:

• gateway/run.py — Detect user file attachments, download to cache
• tools/environments/base.py — Add upload_file() to BaseEnvironment
• Conversation injection — Add file context to user message

Phase 3: Large File Handling — ~4h (optional)

• Content-addressed file cache (~/.hermes/file_cache/{hash[:2]}/{hash})
• S3/MinIO presigned URL generation for oversized files
• Auto-cleanup daemon with configurable TTL
• Telegram file_id caching for dedup on re-sends

Estimated Effort

Phases 0+1 deliver the core value. Phase 2 completes bidirectional flow. Phase 3 handles edge cases.

Design Doc

Full design document with backend-specific implementation notes: plans/file-transfer.md

Research Sources

Cloud IDEs: Gitpod, Coder, code-server, JetBrains Gateway, VS Code Remote
Notebooks: Jupyter, Colab, Kaggle, IPython FileLink
Containers: Docker Archive API, kubectl cp, Podman
CI/CD: GitHub Actions artifacts, GitLab CI, Jenkins stash/unstash
AI APIs: OpenAI Responses API, Anthropic Files API, Gemini File API, E2B
Novel tools: transfer.sh, croc, magic-wormhole, Kitty protocol, Mutagen, rclone
Protocols: tus (resumable uploads), WebDAV, 9P, ZMODEM, WebContainers
Agent codebases: OpenHands, Composio, Pi-Mono, Codex, Cline, OpenCode