agent-to-owner-file-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

---

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