Files and Output
Every crew container has a structured file system that separates agent workspaces, output, secrets, and shared space. Crewship provides REST APIs for listing, uploading, and downloading files, plus real-time WebSocket events for file changes.Agent File System Layout
Inside each crew container, the file system is organized into purpose-specific directories:File Listing
List files for a specific agent or an entire crew.Agent Files
The endpoint resolves the agent’s crew and slug, then fetches files from the container via IPC.
Crew Files
File Download
Download a file from an agent’s or crew’s container.Agent File Download
Crew File Download
application/octet-stream with a Content-Disposition header for the filename.
Table previews in chat
CSV and TSV artifacts open as read-only tables with row filtering, column sorting and virtualized rows. Column letters and row numbers always refer to the original file, including after filtering or sorting. Quoted separators, multiline fields, escaped quotes, Unicode and empty cells are preserved. Formula-like values remain text. Select source rows and choose Ask about selection to append a visible reference to your existing chat draft. Nothing is sent automatically. The reference includes the file path, source agent, original cell coordinates, selected values and a SHA-256 snapshot identity. A refreshed file clears the old selection. File reads still require your current access; denial removes the displayed snapshot. Parsing runs in a cancellable local worker with a five-second timeout. Preview limits are 5 MiB UTF-8 input, 20,000 rows, 100 columns, 200,000 cells and 32,768 characters per cell. Selection is limited to 200 cells and 12,000 UTF-8 bytes of context. Exceeding a limit produces an explicit download fallback rather than a truncated table. File contents are not sent to an external parser. XLSX artifacts use the same read-only grid with a worksheet selector. Original worksheet names, row numbers and column letters appear in selection context. Saved numeric and string values are preserved; dates use ISO timestamps. Formatting, merged-cell layout, charts and images are outside the preview. Formulas are never calculated: cached results are shown, and formulas without saved results have an explicit marker. XLS and XLSM remain download only. XLSX parsing runs in a separate local worker using pinned MIT-licensedread-excel-file 9.3.12. A streaming ZIP/XML preflight counts actual decompressed output before the reader sees a normalized workbook. Limits are 5 MiB input, 20 MiB total expanded ZIP data, 128 ZIP entries, 10 worksheets, 20,000 rows, 100 columns, 200,000 rectangular cells across sheets, 32,768 characters per cell and 10 MiB displayed text. A five-second timeout terminates the worker. Sparse coordinates and repeated shared strings count toward the cell/text budgets. These are input/output budgets, not a browser heap guarantee.
Encrypted, damaged, macro-enabled, DTD-bearing or externally linked workbooks receive an explicit download fallback. ZIP paths, duplicates, checksums and XML depth/node counts are checked. Preview parsing never executes macros, formulas or cell HTML, and does not fetch external relationships. Selection uses the same draft-only, versioned 200-cell / 12,000-byte limit as CSV/TSV.
File Upload
Upload a file to an agent’s or crew’s container.Agent File Save
Crew File Save
path query parameter specifies the destination path inside the container.
File save operations require the
create permission (MANAGER role or above). MEMBER and VIEWER role users cannot upload files.Output Directory Convention
Agents write their output to/output/{agent-slug}/. Per-run deliverables live under /output/{agent-slug}/runs/{runID}/ and supported formats appear under Output files in the Artifacts panel of the chat’s right drawer. That panel also lists documents edited in the chat and the agent’s document access, but its output files have no versions or sharing: they are not versioned artifacts (see Artifacts in chat for the difference). Hidden/internal directories and attachments remain excluded from that list; the existing file API still authorizes listing and reads. This directory is the primary location surfaced in the UI Files panel. When an agent produces output files (generated code, reports, images), they should be written to this directory.
Shared Crew Space
The/crew/shared/ directory is accessible to all agents in a crew. Use it for:
- Shared configuration files
- Inter-agent data exchange
- Common resources needed by multiple agents
/crew/shared/.memory/ subdirectory holds crew shared memory — FTS5-indexed knowledge shared across all agents. The Lead agent writes to CREW.md and topics/*.md; all agents can search it. See the Memory System guide for details.
File Events via WebSocket
File changes inside crew containers are broadcast in real-time via WebSocket on thecrew:{crewId} channel, as file.event messages.
Subscribing
Event Types
Event Payload
File watching uses
fsnotify under the hood. The file watcher monitors the storage base path for changes and broadcasts events to all WebSocket clients subscribed to the relevant crew channel.Channel Authorization
Subscribing tocrew:{crewId} requires membership in the crew’s workspace. The WebSocket hub verifies workspace membership before allowing the subscription.
What’s Next
WebSocket Reference
Full WebSocket protocol reference including all channel types and event formats.
Container Isolation
How file system permissions and UID boundaries protect agent data.