Besides the recordings that voice and meeting connectors bring in, the owner can add material to the Inbox directly: drop a file onto the Inbox, choose it with + Add, paste it with Ctrl/Cmd+V while the Inbox has focus, or add a link (type it into + Add, or paste a URL onto the Inbox). Each file becomes an Inbox item like any other: it gets a Knowledge fact, the 🔗 Share ▾ menu (RFC, Knowledge, DIBS) and the route history.
Adding files is for the owner and read-write sessions. Read sessions do not see the drop zone, the + Add button or the paste handling, and the API refuses them (403).
The hive decides the type from the content, never from the file name or
the browser's MIME type alone: it checks magic bytes first (an executable,
archive, PDF, Office or media file renamed to .txt is refused), then that
the file is UTF-8 text, then that it parses as the format its extension asks
for. A file without an extension is read as JSON when it parses as JSON and
as plain text otherwise. A zip archive is refused unless it is named .docx
and opens as a Word document.
| Type | Extensions | What the item shows |
|---|---|---|
| Markdown | .md, .markdown |
the text as is; the first # heading becomes the title |
| Plain text | .txt, .text, .log |
the text as is |
| JSON | .json |
a one-line summary (top-level keys or array length) and the pretty-printed document in a fenced json block |
| JSON Lines | .jsonl, .ndjson |
the record count and the first 20 records in a fenced block; every line is validated |
| YAML | .yaml, .yml |
a one-line summary and the document in a fenced yaml block (parsed with gopkg.in/yaml.v3) |
| CSV / TSV | .csv, .tsv, .tab |
row and column counts and a markdown table of the first 20 rows (20 columns at most) |
| Word | .docx |
headings (Title and Heading 1 to 6 styles) as #, paragraphs, bulleted and numbered lists (by level) as - items, and tables as markdown tables; deleted text and field codes are left out; the title comes from the document properties, else the first heading. Read in Go with archive/zip and encoding/xml (standard library): at most 1000 zip entries, 200 MiB declared uncompressed in all, 50 MiB per part (checked while inflating, not only from the header) and a 100:1 compression ratio per entry; a part with a DOCTYPE or an entity the decoder does not know is refused (XXE), and nothing is fetched |
.pdf (or a file without an extension that starts with %PDF-) |
one ## Page N section per page with text, a page-count summary, and the document title from its Info dictionary. Parsed out of process in the hive-pdftext sandbox with github.com/ledongthuc/pdf (BSD-3-Clause, pure Go): at most 200 pages and 1 MiB of text; a PDF without a text layer is refused with "no text layer (scanned PDF); OCR not supported yet" |
|
| Audio | .mp3, .m4a, .aac, .wav, .ogg, .opus, .webm |
an audio item with ▶ Play through the same-origin stream (served from this hive's disk) and 🎧 Transcribe; when transcription is enabled and consented, the hive queues the transcription as soon as the file is added. The content must carry the container's signature (ID3 or MPEG frame sync, ADTS, ftyp, RIFF/WAVE, Ogg, EBML) |
| Video | .mp4, .mov |
the same as audio: only the audio track is used (for transcription and playback); there is no video playback |
| HTML | .html, .htm, and web pages behind a link |
readable markdown: the <title> names the item; the <article> or <main> (else <body>) is kept with headings, paragraphs, lists, quotes, code, tables, link targets and image alt text; scripts, styles, forms, navigation, footers, asides and hidden elements are dropped. Parsed with golang.org/x/net/html (BSD-3-Clause); nothing is executed and nothing the page references is loaded |
Text is validated as UTF-8 (a UTF-8 BOM is dropped; UTF-16 is refused with
"save the file as UTF-8") and newlines are normalised to \n. The fenced
previews are bounded at 256 KiB and the item text at 1 MiB; the whole file is
always stored.
Not supported (the item is refused with a message saying what to do):
| File | Message |
|---|---|
Legacy Word .doc (and .xls, .ppt) |
save it as .docx or PDF and try again |
RTF, OpenDocument .odt |
save it as .docx, PDF or plain text |
PowerPoint .pptx |
export the slides as PDF |
Excel .xlsx |
export the sheet as CSV |
| Executables, archives, images, anything else | unsupported file type |
- The browser checks the drop against the limits below (too many files, too large, empty, an extension the hive does not read) and sends each accepted file on its own request, so its row shows upload progress and its own error.
- The hive sniffs the content, extracts markdown in-process with a 30-second
timeout, and stores the upload under
<data>/connector-state/uploads/<id>/(directory 0700, files 0600):original(the file as dropped),extracted.mdandmeta.json(who added it, when, its size and SHA-256). - It writes a Knowledge fact to
<data>/connectors/personal/upload-<id>.mdand reindexes that vault, so knowledge search finds the text at once. The extracted text sits in the fact inside a nonce-tagged<untrusted-inbox-data>envelope. - The item appears as upload · notes.md, with who added it and when. ▸ Text shows the extracted markdown.
Every file, accepted or refused, is audited as inbox_upload with the user,
the item id, the detected kind, the size and the outcome or refusal code; the
file's content and name are not written to the audit log.
An audio or video file is streamed straight to connector-state/uploads/<id>/original
(never held in memory), capped by inbox.recording.max_bytes and the uploads
quota, and its item starts pending: it has no text until it is
transcribed. ▶ Play streams it from this hive's disk through the same
same-origin endpoint recordings use (GET /api/inbox/upload/<id>/audio/stream,
with Range for seeking), and transcription reads the same file locally, so
with whisper the audio never leaves the hive. When inbox.transcription is
enabled and consented, the transcription is queued as soon as the file is
added (audited as inbox_transcribe, actor = who added it); otherwise the
item shows the usual reason 🎧 Transcribe is unavailable. The machine
transcript is written into the item's Knowledge fact like any recording's.
The original is deleted after inbox.uploads.media_retention_days, which
defaults to inbox.recording.retention_days (5 days); the transcript, the
item and the fact stay. Video files keep only their audio track: there is
no video playback. The browser request may take up to 20 minutes to arrive
(the dashboard's 30-second read timeout is lifted for uploads).
PDF parsers have a long history of bugs, so the hive never parses an
uploaded PDF in its own process. It runs /usr/local/bin/hive-pdftext the
same way it runs the whisper transcription sandbox:
- as the separate
hive-transcribeuid (no home, shell or supplementary groups), reached throughsu-exec, with an environment of onlyPATHandLC_ALL; - under
prlimit(1 GiB address space, CPU seconds = timeout + 10, file size = the PDF's size, 32 open files, no core dumps) andnice -n 10; - in an empty network namespace (
unshare --user --net) where the kernel allows unprivileged user namespaces; - with the PDF on stdin, copied into a private 0700 work dir (file 0600) that is removed on exit, and only JSON on stdout (capped);
- with a 60-second wall clock, after which the whole process group is killed.
HIVE_PDF_SANDBOX, HIVE_PDF_RUN_AS and HIVE_PDF_MEMORY_MB override the
path, the uid and the memory cap. When the sandbox is not in the image, PDF
uploads are refused with "PDF reading is not available on this hive".
A link is fetched by the hive itself, once, when it is added, and its body
goes through the same type pipeline as a dropped file: an HTML page becomes
text, a link to a .json, .csv or .md file becomes that kind (the file
name in the URL or Content-Disposition, else the response Content-Type,
picks the format, and the content must still pass the sniff and the parse).
YouTube and other streaming pages are read as HTML pages, never as video;
links to audio or video files are refused for now.
The item is titled by the page <title>, else the file name, else the URL,
and shows link · host. The URL is kept as the item's provenance (and the
fact's source_url) only.
Fetch rules (SSRF protection):
httpandhttpsonly; a link with a user name or password is refused.- The hive resolves the host itself and connects to the address it checked;
if any answer is blocked the link is refused, so a second
(rebinding) answer is never used. Blocked: loopback, RFC 1918 private,
link-local (including the cloud metadata address
169.254.169.254), CGNAT100.64.0.0/10, multicast, reserved and documentation ranges,0.0.0.0/8, IPv6 unspecified, loopback, unique-localfc00::/7(includingfd00:ec2::254), link-local and site-local, Teredo, and IPv4 addresses embedded in IPv4-mapped, NAT64 and 6to4 addresses; host nameslocalhost,*.localhost,*.local,*.internalandmetadata. - Every redirect hop is checked the same way, at most 3 redirects, and a
redirect never carries
AuthorizationorCookie. - The body is streamed through a limit (
inbox.uploads.max_file_bytes); connect 10 s, TLS 10 s, response headers 15 s, whole fetch 60 s. - Requests send
User-Agent: hive-inbox/<version>. HTTP(S)_PROXYfrom the environment is not used (a proxy would resolve the name again). Whennetwork.upstream_proxymatches the host, the hive asks the proxy toCONNECTto the checked IP and port.
All limits have defaults; inbox.uploads in hive.yaml overrides them and
the environment overrides both (a non-positive or malformed value falls
through).
| Setting | Environment | Default | |
|---|---|---|---|
inbox.uploads.max_file_bytes |
HIVE_INBOX_UPLOADS_MAX_FILE_BYTES |
26214400 (25 MiB) |
largest text document |
inbox.uploads.max_files_per_drop |
HIVE_INBOX_UPLOADS_MAX_FILES_PER_DROP |
20 |
files in one drop or one request |
inbox.uploads.quota_bytes |
HIVE_INBOX_UPLOADS_QUOTA_BYTES |
2147483648 (2 GiB) |
everything stored under connector-state/uploads |
inbox.uploads.document_retention_days |
HIVE_INBOX_UPLOADS_DOCUMENT_RETENTION_DAYS |
0 (keep) |
delete a document's original after this many days |
inbox.uploads.media_retention_days |
HIVE_INBOX_UPLOADS_MEDIA_RETENTION_DAYS |
inbox.recording.retention_days (5) |
delete an audio or video original after this many days |
inbox.recording.max_bytes |
209715200 (200 MiB) |
largest audio or video file (the recording cap) |
inbox:
uploads:
max_file_bytes: 10485760
quota_bytes: 1073741824
document_retention_days: 365A retention sweep runs at boot and then hourly. It deletes only the
original file: the extracted text, the meta, the item, its Knowledge fact
and its share history stay. Text documents are kept unless
document_retention_days is set; audio and video originals go after
media_retention_days (5 days), the same as recordings made in the hive.
- Files stay on this hive's data volume. Nothing is sent anywhere when a file is added.
- The extracted text reaches an LLM only when someone shares the item (for
example → RFC hands it to a hive agent), and then only inside the
<untrusted-inbox-data>envelope that tells the model the text is data, not instructions. The same envelope fences it in the Knowledge fact. - The browser request carries the session cookie (SameSite=Lax), and the hive
also refuses a request the browser marks
Sec-Fetch-Site: cross-site.
POST /api/inbox/uploads/url (owner or read-write) takes {"url": "..."}
and answers like a single-file upload (201, or 400 link_refused, 413, 415,
422, 502 fetch_failed, 507); refusals and additions are audited as
inbox_upload with origin=link and the host, never the full URL.
POST /api/inbox/uploads (owner or read-write) takes multipart/form-data
with one or more file fields. One file answers 201 with
{results: [{filename, ok: true, source: "upload", item_id, title, kind}]},
or with the status of its refusal: 400 (empty, too_many_files), 413
(too_large), 415 (unsupported_type), 422 (parse_failed), 507
(quota_exceeded); each refused result carries code and error. Several
files answer 200 with one result per file unless all of them failed. See
api-reference/knowledge.md.
GET /api/inbox reports the limits and current usage under
settings.uploads (enabled, max_file_bytes, max_files_per_drop,
quota_bytes, used_bytes, media_retention_days,
document_retention_days, extensions, links).