--- title: "File Attachments | AgentRQ Docs" url: https://agentrq.com/docs/howto-attachments description: "Attach files to AgentRQ tasks and messages from the dashboard, the agentrq-ws CLI or MCP, and learn how previews, public links and retention work." --- [Docs](https://agentrq.com/docs/) / How-To / File Attachments File Attachments # File Attachments Attach files to tasks and messages — from the dashboard or directly from Claude Code via MCP. Share diffs, screenshots, specs, logs, and any other file as part of your human-agent workflow. ## Overview Attachments are files associated with a task or a message within a task. They can be added at two points: when a task is first created, or inline with any reply message. Every attachment is stored server-side and referenced by its attachment ID. Each stored file also gets a public link, which is how the dashboard downloads it and how an agent can fetch it without pulling base64 through MCP. Supported File Types - Images (PNG, JPG, GIF, WebP, SVG) - Code files (.go, .ts, .py, .diff, etc.) - Text documents and logs - PDFs and documents - Any binary file Storage Model - Stored by AgentRQ, on disk or in S3 - Referenced by its attachment ID - Filed under its workspace and task - Public link: no sign-in to open it - Downloadable via MCP, CLI or dashboard - Auto-deleted after 7 days (by default) ## Attaching Files from the Dashboard The dashboard provides two places where you (the human) can attach files, with the "Attach files" button or by drag and drop. These attachments become part of the task's message thread and are visible to both you and any connected Claude Code agent. 1 When Creating a Task In the "New Task" dialog, the attachment area appears below the task body field. Drag and drop files onto it, or click to open a file picker. Multiple files can be attached in one go. - Click the attachment zone or drag files directly - Attach multiple files in one task creation - Files appear as attachment chips before you submit 2 When Replying to a Task In the task detail view, the reply box includes an attachment button (paperclip icon), or you can drop files anywhere on the task. Attach files inline with your reply — they land in the message thread alongside your text. - Click the paperclip icon in the reply composer - Files appear inline in the message thread - Download links shown for each attachment Previewing and Sharing Click an attachment in the thread to preview it. Images, videos, audio and PDFs open right in the preview; other files show their name and type. - Download saves the file under its own name - Copy link puts the file's public link on the clipboard, to share with anyone Tip: Attaching Specs for the Agent A common workflow is to attach a `spec.pdf` or `requirements.md` when creating a task for Claude. Claude can then read it with `task getAttachment` before starting work — no need to paste long documents into the task body. ## Attaching Files from Claude Code Both `task create` and `task reply` accept an optional `attachments` array in their payload. Each attachment object carries the file content as base64-encoded data so it can be transmitted over the MCP protocol and stored server-side. Attachment Object Schema id string Any string. The server gives the stored file its own ID, which is the one to use afterwards filename string Display name shown in the dashboard mimeType string MIME type (e.g. `text/plain`, `image/png`) data string (base64) Full file content, base64-encoded Example: Claude has finished reviewing code changes and wants the human to approve a diff before merging. It creates a task with the diff attached: task create — with attachment ``` task {"action": "create", "payload": { "title": "Review this diff", "body": "I've made the changes — here's the diff for your review.", "attachments": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "filename": "changes.diff", "mimeType": "text/plain", "data": "base64encodedcontent..." } ] }} ``` The same pattern works with `task reply` — Claude can attach a screenshot of a test result, a generated report, or error logs as part of a progress update: task reply — with attachment ``` task {"action": "reply", "payload": { "taskId": "TASK_ID", "text": "Tests are passing. See attached output for details.", "attachments": [ { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "filename": "test-output.txt", "mimeType": "text/plain", "data": "base64encodedcontent..." } ] }} ``` Files travel base64-encoded, which makes them a third larger, and a single request is capped at 4 MB. Keep the files on one task or message under about 3 MB in total. From the command line The `agentrq-ws` CLI takes a file path and works out the name, type and encoding for you. `attachment get` downloads a file through its public link and saves it under the name it was given, in the OS temp directory unless you pass `--out`. ``` agentrq-ws reply TASK_ID "Build is green — log attached" --attach ./run.log agentrq-ws task create "Review the design" --body @brief.md --attach ./mock.png agentrq-ws attachment get ATTACHMENT_ID --task TASK_ID --out ~/Downloads ``` ## Reading Attachments with `task getAttachment` When a human attaches a file to a task or message, Claude Code sees it listed under `Attachments:` with its ID, name, type and, when the file has one, a public link. The `getAttachment` action of the `task` MCP tool looks the ID up on the task and its messages. By default it returns that link instead of the file, so a large PDF does not fill the agent's context. Ask for `base64` when the agent needs the bytes. Action Signature ``` task {"action": "getAttachment", "payload": {"attachmentId": string, "taskId": string, "format"?: "url" | "base64"}} Returns: { filename, mimeType, url } // format "url" (default), when the file has a link { filename, mimeType, data } // format "base64", or when there is no link // data is the file content, base64-encoded. ``` Clients installed before the action tools may still call `createTask`, `reply` (with `chatId`) or `getAttachment` by their old names. Those calls still work: the server maps each one to the matching `task` action. See [Old tool names](https://agentrq.com/docs/mcp-tools#old-names). A typical workflow: the human attaches a specification document when creating a task, and Claude reads it before beginning work. Example Workflow: Human Attaches a Spec 1 Human creates task "Implement payment module" and attaches `payment-spec.pdf` 2 Claude receives the task notification via the MCP channel, with the attachment's ID, name, type and link listed 3 Claude calls `task getAttachment` with `"format": "base64"` and receives the PDF content 4 Claude decodes, reads the spec, and proceeds with implementation — no need for the human to paste the content manually task getAttachment call ``` // The task notification lists the attachment: // Attachments: // - id=0jN4sT2kQ8p name=payment-spec.pdf type=application/pdf url=https://… task {"action": "getAttachment", "payload": {"attachmentId": "0jN4sT2kQ8p", "taskId": "TASK_ID", "format": "base64"}} // Returns: { "filename": "payment-spec.pdf", "mimeType": "application/pdf", "data": "JVBERi0xLjQKJcfsj6IK..." } ``` ## Best Practices Good Uses for Attachments - Diffs and patch files for review - Screenshots of errors or UI states - Test output and logs - Specification documents and PRDs - Config files and environment templates - Generated reports or summaries Keep in Mind - Keep files small: a request is capped at 4 MB, base64 included - Attachments are stored server-side — avoid attaching sensitive credentials - Attachment links are public: anyone who has the link can open the file, without signing in - Attachments are deleted after 7 days by default. Self-hosters can change this with `AGENTRQ_APP_ATTACHMENT_RETENTION`, or keep them in S3 with `AGENTRQ_ARTIFACTS_STORAGE=s3` - Self-hosters: back up the `_storage` directory regularly - Someone with one link can work out the links of the task's other files: share a link only with someone who may see the whole task - Images, videos, audio and PDFs preview in the dashboard. HTML, SVG and other files a browser could run always download instead of opening ## Related Pages [Workflow Patterns Common agentic patterns using tasks and replies](https://agentrq.com/docs/howto-workflows) [Task Lifecycle Status flows, replies, and task management](https://agentrq.com/docs/tasks) [Workspace MCP Reference Every action of the 7 MCP tools](https://agentrq.com/docs/mcp-tools)