Agent-Ready Files
A files collection takes files your end users upload and turns each one into visible text and page images that an agent can read, search and cite over the Flux API and MCP. Every file arrives in a labelled untrusted envelope with a verdict. The agent sees what a person sees: text hidden in the file is not delivered and is reported as a finding.
What an agent receives
| An agent receives | An agent never receives |
|---|---|
| Visible text, read by OCR from FoxNose's own rendering of the file, as page-anchored markdown. | The original file, or a link to it. |
Page images of that rendering, as short-lived links on request (include_links), with unreadable and hidden regions redacted. | Text the rendering does not draw: hidden layers and runs, comments, metadata, off-page text, a PDF's own text layer. |
A verdict, clean or suspicious, with the finding kinds behind it. | Text below the legibility floor. |
| Flags for unreliable text and redacted regions, with page and box. | blocked or rejected files. Their bytes are purged. |
A taint map, tainted_paths, naming every file-derived value. | Findings evidence and detector scores. |
FoxNose renders every file with its own pinned renderer: documents become PDFs, PDF pages are rasterised, images are re-encoded. That rendering defines what a person sees. Text comes only from OCR of it, never from the file's text layer, and is delivered unaltered: the PII screen reports personal data but does not mask it.
Redaction. A region located as unreadable, hidden or below the legibility floor is painted over in the page images (redacted_png) and listed in redacted. Tiny text that OCR misses inside a line it otherwise read is not located, so it is not redacted.
Unreliable text. Latin and Cyrillic text is delivered. A line or page in another script is replaced by text not recognised: unsupported script. Low-confidence words and pages below the minimum text height are delivered and flagged. See content_flags.
Supported inputs
An agent_ready collection accepts the kinds its policy allows (allowed_kinds): image and document. Anything else is rejected as unsupported_format. A storage_only collection also accepts other file types and archives. The format is identified from content, not from the MIME type or extension. Details are on File Checks.
- Images: JPEG, PNG, WebP, GIF and HEIC/HEIF, single frame.
- Documents: PDF (up to 100 pages), DOCX, ODT, RTF, TXT and Markdown.
- Rejected: encrypted or XFA PDFs, password-protected documents, documents with macros, embedded objects or linked external content, animated images, empty files.
storage_onlyonly: archives, spreadsheets, presentations and.doc.
How a file becomes agent-ready
- Scan. The original is malware-scanned before anything parses it. An infected file is
blockedand purged. - Render. The file is rendered in a disposable sandbox with no network access.
- Read and check. OCR reads the pages. Detectors look for hidden text, unreadable regions, Unicode smuggling, explicit imagery, prompt attacks, sexual content and PII.
- Verdict. The findings and the collection's policy produce a verdict.
- Safe copy. An image-only PDF of the redacted pages is stored (a PNG for an image).
- Publish. The record, its search rows and embeddings go live in one transaction. From here, agents can read and search the file.
Trust model
Everything that comes from the file is untrusted, the filename included, and is marked so twice:
- For the model: the value sits inside an
<<untrusted-upload:BOUNDARY>>block that says to treat it as data, not instructions. The boundary is random per response and cannot be closed from inside. - For your code:
tainted_pathslists every file-derived path, and over MCP each such value instructuredContentis wrapped as{"$untrusted": …}.
The verdict, its reasons and the flags travel with the content. Fields your application writes, such as file.name and the collection's own fields, are not tainted. The exact format is in the references: over MCP and over the Flux API.
Detectors are signals, not a guarantee, and FoxNose does not prevent visible prompt injection: text a person can read is delivered, and the prompt-attack screen only flags it. The envelope advises the model; it cannot force it. Enforcement belongs in your agent's design, for example a dual-LLM setup, CaMeL, or the "Rule of Two". FoxNose supplies the inputs: verdict, reasons, taint map, flags, and a policy that can quarantine suspicious files before any agent reads them.
Isolation. End-user uploads go only into strict-reference collections, where every file belongs to an owner record the calling key can access. A non-strict files collection is shared by everyone who can read it; use it for your own team's files.
Processing modes
agent_ready (default) | storage_only | |
|---|---|---|
| Malware scan | Yes | Yes, the only automatic block |
| Rendering, OCR, detectors, moderation | Yes | No |
| Search | Page text, chunk-level, with embeddings | Metadata and your fields only |
| Agents receive | Text, flags, verdict, page-image links | Metadata, marked content not processed: storage-only collection |
| Safe copy | Yes | No |
| Moderation rules | Available | Not available |
In both modes agents never get the original; people download it through the dashboard or the Management API. processing can be changed only while the collection holds no files. A storage_only collection refuses a file whose content contradicts its declared type or extension, such as a program named invoice.pdf.
Verdicts and findings
Each analysis records findings, each with a severity: info, suspicious or block. The highest severity sets the verdict:
| Verdict | Meaning |
|---|---|
clean | Nothing suspicious or block. |
suspicious | At least one suspicious finding. With suspicious_action: deliver (default) the file is published with the verdict; with quarantine it waits for a reviewer. |
blocked | At least one block finding. The bytes are purged and a tombstone remains. |
rejected | Unsupported format, disallowed kind, over a limit, or processing failed. |
Agents see only clean and suspicious records, with reasons listing the finding kinds. A customer moderation rule appears as policy_rule:<rule id>. The uploader never sees verdicts: the status endpoint returns processing, accepted or rejected with one of malware, prohibited_content, unsupported_format, too_large, processing_failed.
Finding kinds
| Kind | What it reports | Default | Can be set to |
|---|---|---|---|
malware | The malware scan found an infection. | block | Not overridable |
explicit | Explicit imagery (label Explicit, confidence 50+) on any page. agent_ready only. | block | suspicious, info, with acknowledge_explicit_delivery: true |
moderation | Another moderation label. | suspicious | block, info |
policy_rule | One of your moderation rules failed. Needs moderation turned on. | The rule's action | Set by the rule |
hidden_text (concealment) | Text the rendering does not draw: invisible PDF text, zero-area clipping, hidden runs, fields and sections, text in the background colour, tiny fonts, collapsed scale, text lost in conversion. | suspicious | block |
hidden_text (annotations) | Comments, tracked changes, field instructions, alt text. | info | suspicious, block |
low_legibility_text | Text in the image below the legibility floor. Redacted. | suspicious | block |
unicode_smuggling | Invisible or direction-changing code points. Stripped. | suspicious | block, info |
prompt_attack | The prompt-attack screen flagged the text. | suspicious | block |
sexual_text | Sexual prose. | suspicious | block |
pii | Personal data. Lists entity types only, never values. | info | suspicious, block |
text_unreliable | unsupported_script, low_confidence or low_resolution. | info | suspicious, block |
unread_text_region | A text-like region OCR did not read. Redacted. | info | suspicious, block |
mixed_script | Words mixing Latin and Cyrillic letters. | info | suspicious, block |
active_content | A PDF carries active content. Management API only. | info | Not overridable |
An override outside the listed range is refused when the policy is saved.
Explicit imagery is blocked by default, which also blocks some legitimate files, such as clinical photos. Lowering explicit requires acknowledge_explicit_delivery: true, because the page images then reach your agent and its model provider. It does not restore files already blocked. Explicit prose is sexual_text, suspicious by default, so literature and health material is not rejected.
Active content
active_content reports what a PDF viewer could run: JavaScript, launch actions, embedded files, rich media, form submissions and automatic actions. FoxNose runs none of it. The finding is info, never affects the verdict or reaches agents, and holds only counts per kind, never a script or address. It is returned by the Management API in the file's findings. A PDF whose active-content check did not complete is not clean for original_access: when_clean.
Policy
Each files collection has a policy: what to do with suspicious files (deliver or quarantine), severity overrides within the ranges above, which kinds are allowed, when to analyse tables, moderation rules, and original access. Read and replace it with the files policy endpoints.
Every change to the policy is saved as a version. A stricter policy withholds files verdicted under the old version from delivery and search until they are re-verdicted; a looser one withholds nothing and can release quarantined files. Changes reach delivery within about a minute.
Hosted upload links
A hosted upload link lets someone without a FoxNose account upload up to 10 files to a record. Your application creates one with the Management API, or an agent requests one with request_upload. The link expires (30 minutes by default, up to 24 hours) and its token sits in the URL fragment, so it never reaches a server log.
The page shows each file as uploading, checking, received or not accepted, with the reason when the sender can fix it (format, size, failed processing). Security and policy outcomes are never shown to the sender.
Safe copy and downloads
People download files through the Management API or the dashboard. Agents never do.
Safe copy
Every agent_ready file has a safe copy: its redacted page images in a PDF (a PNG for an image). It has no scripts, forms, annotations, fonts, metadata or text layer, so nothing in it can run. It is not searchable and is at screen resolution. Its pages are also available one by one as PNGs.
Downloads
The Management API returns the original, the safe copy and single pages, each as a link that expires within five minutes. The original carries a warning when the file has active content or a suspicious finding. The record's file block says whether each download is available, and a refused download answers 409 with a reason.
While a newer analysis is processing, failed or quarantined, the last published version is served. A file quarantined on its first analysis is served to reviewers only. Downloads of a quarantined file are audited.
Original access
original_access controls whether the original can be downloaded, for every caller, reviewers included. It changes nothing else, and switching back to allowed restores downloads.
| Value | The original is downloadable |
|---|---|
allowed | Whenever a download is allowed at all. |
when_clean | Only with no active_content and no suspicious or higher finding; a PDF also needs a complete active-content check. Otherwise 409 original_withheld. |
disabled | Never. 409 original_disabled. |
storage_only collections do not accept when_clean (409 original_access_requires_agent_ready).
Moderation
Base moderation checks every page of an agent_ready collection and keeps its labels internal. Turn on moderation for a files collection to expose those labels and act on them. It is a setting of the collection: Settings → Files in the dashboard, or Turn On Moderation in the API. It adds no file units, and it adds:
- a read-only
moderationfield on each record, written once its labels are stored, with the model version and the highest confidence of each label; moderation_rulesin the policy.
A rule names a label or category, a confidence threshold and an action (info, suspicious or block); see the rule format. Up to 50 rules per collection. Rules only add findings and never lower explicit.
Turning it on creates no rules and changes no verdict; published files that already have moderation results get their stored labels without being re-processed. It works in agent_ready collections only (409 addon_requires_agent_ready). Turning it off removes the rules; values already written stay on the record until the file is re-analysed or erased.
Where file data lives
| Data | Where |
|---|---|
| Upload, malware scan, conversion of some image formats | United States |
| Original, staged copy, rendered pages, OCR output, moderation and screening results, safe copy | FoxNose storage in the project's region |
| Content, findings, embeddings, search rows | FoxNose databases in the project's region |
Each upload uses a single-use token FoxNose issues. Once the scan is clean, the file is copied into FoxNose's encrypted storage in the project's region (Frankfurt for the EU zone), and all further processing happens there.
GDPR mode does not cover the upload, malware scan and image conversion, which happen in the United States. In a GDPR-mode project the dashboard asks for consent before creating a files collection or installing the File add-on. The Management API and SDKs have no consent step; for them, this section is the notice.
Erasure. Deleting a record or its collection erases every FoxNose copy of the file: all versions of the original, every derivative, search rows, embeddings, file-derived content and findings evidence. Incomplete erasures are retried and alerted on. Database backups expire on their own schedule.
Related
- Files API — policy, uploads, review and downloads.
- MCP Files tools — uploads and reading files over MCP.
- File content over MCP and over the Flux API — the exact fields an agent receives.
- Billing & Usage — file units and allowances.
- File Checks — what each mode checks and refuses.
- Files Limits — sizes, rates and retention.
- Upload a File and Let an Agent Read It — a walk-through.
- MCP Server — the tools that read files.
- Strict-Reference Modeling — the collection shape for end-user uploads.
- GDPR & Data Residency — storage zones and GDPR mode.