Agent-to-Owner File Bridge

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.

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

---

🔒 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.