Skip to main content

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

Query parameters: The endpoint resolves the agent’s crew and slug, then fetches files from the container via IPC.

Crew Files

Query parameters:

File Download

Download a file from an agent’s or crew’s container.

Agent File Download

Crew File Download

File paths are sanitized server-side. Absolute paths and path traversal (..) are rejected. Only relative paths within the container’s file system are accepted.
The response streams the file as 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-licensed read-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

The request body contains the raw file content. The 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.
The UI Files panel displays these files per-agent, allowing users to browse and download output without direct container access.

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
Any agent in the crew can read from and write to this directory. The /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 the crew:{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 to crew:{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.