Agent-to-Owner File Bridge

SKILL.md

---
name: "Agent-to-Owner File Bridge"
description: "Use this skill whenever an AI agent needs to share files, export results, upload outputs, or send data to its owner. Securely uploads files from the agent's private workspace to a hosted server and returns a direct download/preview URL. Use whenever the user says things like 'upload this file', 'share this with me', 'give me a link', 'send me the output', 'export results', or whenever the agent generates a file the user needs to access."
version: "3.0.2"
compatibility: "Requires: Python 3.8+ (autonomous mode only), pip, optionally Node.js for localtunnel. All autonomous-mode actions (server start, tunnel, key generation) require explicit user approval before execution."
env:
  API_KEY: "Secret key for authenticating with the bridge server. In Manual Mode: provided by the user from their own hosted server. In Autonomous Mode: generated by the agent and stored in .env in the agent workspace — user must explicitly approve this step. Rotate or delete after each temporary session."
  SERVER_URL: "Base URL of the bridge server (e.g. https://your-domain.com/upload/ or http://IP:5000). Provided by the user or set after the tunnel is opened."
tags:
  - file-upload
  - utility
  - automation
  - bridge
---

# Agent-to-Owner File Bridge

Upload files from an agent's workspace and generate a download/preview URL for the owner. The bridge server is open-source, self-hosted, and all sensitive steps require explicit user permission.

**GitHub Repository:** [https://github.com/mrbeandev/OpenClaw-File-Links-Tool](https://github.com/mrbeandev/OpenClaw-File-Links-Tool)

---

## 🔒 Permissions & Security Boundaries

This skill has two modes. Both require the **user to explicitly choose and approve** before any action is taken:

| Action | Who approves | Scope |
| :--- | :--- | :--- |
| Running `server.py` | User must say "yes, start it" | Agent's own workspace only |
| Opening a public tunnel | User must say "yes, expose it" | Temporary, agent-session-scoped |
| Generating & storing API key | User must say "yes, generate it" | `.env` in agent's workspace |
| Uploading a file | User must confirm file + destination | Named file, single upload |

The agent **never initiates any of these actions silently**. Every step is gated by an explicit user confirmation.

---

## 🛠 Setup

The bridge server is a single open-source PHP or Python file deployed by the **user** on their own infrastructure.

### Option A — PHP (recommended for shared hosting)
1. Place `index.php` on any PHP host.
2. Set `API_KEY` in a `.env` file.
3. Note the URL and key.

### Option B — Python (VPS / local machine)
1. `pip install flask` then `python server.py`.
2. Set `API_KEY` in `.env`.
3. Note the URL and key.

Once set up, give the agent your **Server URL** and **API Key** — no further setup needed.

---

## 🤖 Agent Workflow

**When the user asks to upload or share a file:**

1. **Check for Bridge:** Is a Server URL and API Key already configured in this session? If yes, skip to step 4.

2. **Onboarding:** Ask the user exactly one question:
   > "I can help you share files. How would you like to handle the hosting?
   > 1. **Manual Mode (recommended):** You already have a server — give me the URL and API Key and I'll upload right away.
   > 2. **Autonomous Mode:** I'll set up a temporary local bridge in my workspace and open a public tunnel. This requires your permission at each step."

3. **Autonomous Mode (only if user explicitly chooses it):**

   **Step 3a — Get user confirmation before starting:**
   > "To run the bridge server I will: (1) copy `server.py` from the open-source repo, (2) generate an API key and save it to `.env` in my workspace, (3) start the server on port 5000. May I proceed?"
   - Only proceed if the user says yes.

   **Step 3b — Get user confirmation before opening the tunnel:**
   > "To make the server reachable I will open a temporary public tunnel (via localtunnel or localhost.run). This creates a public URL pointing at my local port 5000. The link expires when my session ends. May I open the tunnel?"
   - Only proceed if the user says yes.
   - After tunnel is open, tell the user: *"The tunnel URL is [URL]. This link is temporary and will stop working when this session ends."*

4. **Upload:**
   - `POST` the file to the server URL with `X-API-Key` header and `file` form-data field.
   - The JSON response contains `url` (direct download) and `view_url` (rich in-browser viewer).
   - **Give the user `view_url`** for text, code, images, and ZIPs — it renders content instantly in the browser.
   - Give `url` for binary files or when a raw download link is requested.

---

## 📋 API Reference

| Endpoint | Method | Action |
| :--- | :--- | :--- |
| `/` | `POST` | Upload a file (`file` form-data field) |
| `/?action=list` | `GET` | List all uploaded files |
| `/?action=view&file=...` | `GET` | Rich viewer (ZIP: add `&inner_file=path`) |
| `/?action=delete` | `POST` | Delete files (JSON: `{"files": ["name..."]}`) |

Authentication: `X-API-Key` request header on all endpoints.

---

## 📎 Bundled Reference

See `api_instructions.txt` for a concise API cheat-sheet with curl examples.