agent-share
Self-hosted file sharing and HTTP tunneling. Files open in a browser-based viewer. Ports are proxied through a public URL.
How it works
Every share gets a unique subdomain:
https://word-word-123.share.chesher.xyz
Files open in a viewer that renders the content inline — markdown is rendered, code is highlighted, diffs get a side-by-side view, images display directly, audio and video play in the browser. A download button is always present.
Tunnels proxy an HTTP port on the agent's machine through a WebSocket connection to the same subdomain. The recipient accesses the live service as if it were a public URL.
Quick start
# Configure the CLI once agent-share config set-server https://share.chesher.xyz agent-share config set-key YOUR_API_KEY # Share a file agent-share file ./report.md # Expose a local port agent-share tunnel 3000
Expiry
| TTL | Duration |
|---|---|
1h | 1 hour |
24h | 24 hours (default) |
7d | 7 days |
permanent | No expiry |
Using a share link
Share links open directly in the browser. No account or software required.
Top bar
Every viewer page has a fixed top bar with:
- File type icon and filename
- File size and time until expiry
- Download button — always downloads the original file
- Dark/light toggle — preference is saved and applies to all future share links on your device
Tabs
Content types with multiple views use tabs that switch in place without reloading the page:
| Type | Tabs |
|---|---|
| Markdown | Preview, Raw |
| Code | Highlighted, Raw |
| JSON | Formatted, Raw |
| Diff / Patch | Unified, Side by Side, Raw |
| CSV | Table, Raw |
| SVG | Preview, Source |
| Image | Image, Info |
URL parameters
| Parameter | Effect |
|---|---|
?raw=1 | Serve the raw file inline, bypassing the viewer |
?download=1 | Trigger a file download |
Agent / MCP tools
agent-share is registered as an MCP server in OpenClaw. Four tools are available in every agent session.
share_file
Upload a local file and get a public URL. The recipient sees the appropriate viewer for the file type.
share_file(path="/tmp/report.md", ttl="7d")
# returns: { url, slug, expires_at }
| Parameter | Required | Default | Description |
|---|---|---|---|
path | Yes | — | Path to the file |
name | No | random | Custom slug |
ttl | No | 24h | Expiry: 1h, 24h, 7d, permanent |
Common patterns
# Markdown report — renders with full formatting share_file(path="/tmp/analysis.md", ttl="7d") # Git diff — renders unified and side-by-side views share_file(path="/tmp/changes.patch", ttl="24h") # CSV data — renders as a sortable table share_file(path="/tmp/results.csv", ttl="1h") # Screenshot or diagram — displays inline share_file(path="/tmp/diagram.png", ttl="24h") # Permanent link with custom slug share_file(path="/tmp/spec.md", name="project-spec", ttl="permanent")
share_tunnel
Expose a local HTTP port through a public URL. The tunnel is active for the duration of the tool call.
share_tunnel(port=5173, ttl="2h")
# returns: { url, slug }
| Parameter | Required | Default | Description |
|---|---|---|---|
port | Yes | — | Local port to expose |
name | No | random | Custom slug |
ttl | No | 24h | Expiry |
list_shares
Returns all active shares and tunnels.
list_shares()
# returns: [{ slug, type, url, filename, size, created_at, expires_at }]
delete_share
Delete a share or disconnect a tunnel.
delete_share(slug="word-word-123")
CLI reference
The CLI provides the same capabilities as the MCP tools.
Setup
agent-share config set-server https://share.chesher.xyz agent-share config set-key YOUR_API_KEY
Commands
file
agent-share file ./report.pdf agent-share file ./image.png --name my-image --ttl 7d agent-share file ./data.csv --ttl permanent
| Flag | Default | Description |
|---|---|---|
--name | random | Custom slug |
--ttl | 24h | Expiry |
--open | false | Open URL in browser after upload |
tunnel
agent-share tunnel 3000 agent-share tunnel 8080 --ttl 2h
list
agent-share list
rm
agent-share rm word-word-123
API reference
All endpoints require Authorization: Bearer YOUR_API_KEY.
Endpoints
| Method | Path | Description |
|---|---|---|
POST | /api/upload | Upload a file |
POST | /api/tunnel | Register a tunnel |
GET | /api/shares | List active shares |
DELETE | /api/share/:slug | Delete a share |
GET | /health | Health check (no auth) |
POST /api/upload
Accepts multipart form data or a raw body with X-Filename header.
curl -X POST https://share.chesher.xyz/api/upload \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@report.pdf" \ -F "ttl=7d" \ -F "name=my-report"
Response:
{ "slug": "my-report", "url": "https://my-report.share.chesher.xyz",
"filename": "report.pdf", "size": 124580,
"expires_at": "2026-05-17T00:00:00Z" }
POST /api/tunnel
curl -X POST https://share.chesher.xyz/api/tunnel \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ttl":"2h"}'
Response:
{ "slug": "word-word-123",
"url": "https://word-word-123.share.chesher.xyz",
"ws_url": "wss://share.chesher.xyz/ws/tunnel/word-word-123",
"expires_at": "..." }
Connect to ws_url with Authorization: Bearer to activate the tunnel.
Viewer types
The viewer detects file type by extension and MIME type and selects the appropriate renderer.
Supported types
URL parameters
| Parameter | Effect |
|---|---|
?raw=1 | Bypass the viewer — serve the raw file inline |
?download=1 | Force a file download |