Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.crewship.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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: 
Crew Container (crewship-team-{slug})
├── /workspace/              # Temporary scratch space
├── /output/{agent-slug}/    # Agent output (visible in the UI Files panel)
├── /secrets/{agent-slug}/   # Read-only credential files
├── /crew/
│   ├── agents/{slug}/       # Per-agent home directory
│   │   ├── .memory/         # Persistent memory files
│   │   └── .mcp.json        # MCP server config
│   └── shared/              # Cross-agent shared space
DirectoryPurposeVisibility
/workspace/Temporary files, scratch space for agent workInternal to container
/output/{slug}/Agent output filesVisible in UI Files panel
/crew/shared/Files shared between all agents in the crewAll agents in the crew
/secrets/{slug}/Credential files (read-only)Per-agent, injected at startup
/crew/agents/{slug}/Agent home directory with memory and configPer-agent

​
File Listing

List files for a specific agent or an entire crew.

​
Agent Files

GET /api/v1/agents/{agentId}/files
Query parameters:
ParameterTypeDescription
recursivebooleanList files recursively (default: false)
subdirstringSubdirectory to list within the agent’s output
The endpoint resolves the agent’s crew and slug, then fetches files from the container via IPC.

​
Crew Files

GET /api/v1/crews/{crewId}/files
Query parameters:
ParameterTypeDescription
agent_slugstringFilter files by a specific agent slug
recursivebooleanList files recursively (default: false)
subdirstringSubdirectory to list

​
File Download

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

​
Agent File Download

GET /api/v1/agents/{agentId}/files/download?path={filePath}

​
Crew File Download

GET /api/v1/crews/{crewId}/files/download?path={filePath}
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.

​
File Upload

Upload a file to an agent’s or crew’s container.

​
Agent File Save

PUT /api/v1/agents/{agentId}/files/save?path={filePath}

​
Crew File Save

PUT /api/v1/crews/{crewId}/files/save?path={filePath}
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 (MEMBER role or above). VIEWER role users cannot upload files.

​
Output Directory Convention

Agents write their output to /output/{agent-slug}/. This directory is the primary location surfaced in the UI Files panel. When an agent produces artifacts (generated code, reports, images), they should be written to this directory. 
/output/
├── viktor/
│   ├── report.md
│   ├── generated-code.ts
│   └── analysis/
│       └── results.json
├── elena/
│   └── design-spec.pdf
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 files:{crewId} channel.

​
Subscribing

{
  "type": "subscribe",
  "channel": "files:{crewId}"
}

​
Event Types

EventDescription
file_createdA new file was created in the output directory
file_modifiedAn existing file was modified
file_deletedA file was deleted

​
Event Payload

{
  "type": "file_event",
  "channel": "files:crew-uuid",
  "payload": {
    "event": "file_created",
    "path": "output/viktor/report.md",
    "name": "report.md",
    "size": 4096,
    "modified_at": "2025-01-15T10:30:00Z"
  }
}
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 files:{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.