File management
For AI Agents: the Markdown version of this page is at https://ankole.agentbull.com/en-US/docs/file-management/index.md. The documentation index is at https://ankole.agentbull.com/en-US/llms.txt.
In day-to-day work, people share files directly in chat or collaborate in Pod pages, while Agents read and write /drive directly. Open the Console Drive browser when you need to inspect tenant roots while Workers are offline, upload reference datasets, download saved outputs, or reorganize folders across spaces.
Ankole unifies collaboration pages and runtime files in Unified Drive: Ankole.Pod owns the pages tree, permissions, and Trash lifecycle, while Ankole.Files stores tenant-scoped immutable byte blobs in file_objects (keeping embedded document, Base, and Applet assets in pod_files so they do not clutter Drive listings). Session and Background Agent Job working trees (/workspace) live in persistent Agent Home rather than Drive; operators configure the underlying object store via Control-plane drive storage, and 1.x Home imports are covered in Upgrade from 1.0 to 2.0.
Worker /drive mounts and CLI fallback
On FUSE-capable Workers, the root supervisor mounts /drive inside each command or Codex process’s private mount namespace before dropping to uid 1000, exposing the roots permitted by the current execution’s access graph:
| Path | Mode | Contents |
|---|---|---|
/drive/Public |
Read-write | Shared Pod Space pages, folders, and files (projected as plain directories plus ._adoc.md, ._abase, and ._aapp views where applicable) |
/drive/MyDrive |
Read-write | The human owner’s Private space when the Agent acts as that member’s Personal Assistant |
/drive/AgentDrive |
Read-write | The Agent’s private runtime root for saved outputs and generated images outside a conversation |
/drive/ChatDrive |
Read-write | The active conversation’s isolated root for inbound attachments, conversation-generated images, and shared deliverables |
/drive/Brain |
Read-only | Brain knowledge pages (._awiki.md) filtered by the current room and requester disclosure rules |
/drive/Skills |
Read-only | Enabled Skill packages managed in Meta Ankole → Skills (see Skills) |
/drive/AGENTS.md, /drive/DESIGN.md |
Read-only | Effective composed behavior and design contracts managed in Meta Ankole → Agents (see Agents) |
/drive-recovery |
Read-write (local) | Scoped recovery directory where the Worker preserves local draft bytes and diagnostics if a background VFS writeback hits a 412 or 422 conflict |
When a Worker environment cannot mount FUSE during startup probing, Ankole advertises the ankole-files CLI (list, get --node-id, put, mv, rm) over the signed WorkerFiles relay instead. To send a Drive file into chat, reply_attachment accepts either a Drive node_id or a /drive/... path, flushing any pending FUSE writes before capturing the completed object.
Browse and upload in the Console
- Open Drive in the Console for the selected tenant.
- Browse Pod Space, Brain, Private roots (for members and Agents), or Conversation roots—even when no Worker is running.
- Open the target folder and select Upload to upload individual files or directory trees. Uploading to an existing file name replaces that node’s current
object_id.
Organize reference material under clear, stable paths such as customer-research/2026-q3-interviews.pdf. Uploading stores the file in Drive without waking an Agent: mention the path or page in chat when you want an Agent to process it, or submit documents through Learn source when you want Brain to extract durable knowledge.
Attachments, Trash, and retention
Open the action menu beside any non-root item to move, rename, or delete it (roots themselves cannot be moved, renamed, or trashed).
- Unified Drive Trash: Deleting a file or folder moves its subtree into Trash immediately and hides it from Drive and Pod listings. Trashed items remain recoverable by callers with
managepermission untildrive.trash_retention_dayselapses (default30days; setting0retains trashed items indefinitely until the setting changes). Keep important data covered by your regular backup before permanent purge. - Frozen chat attachments: When a message is sent, Ankole records an immutable
object_idreference inmessage_attachments(andankole-pod chat attachment getreads that frozen object). Overwriting, renaming, moving, or trashing the Drive file later leaves already-sent conversation attachments intact.
What persists across Worker restarts
Unified Drive objects live in PostgreSQL and your configured object store, while /workspace repositories and scratch files live in persistent Agent Home; both survive Worker restarts and image updates. Files written only under /workspace stay in Agent Home until the Agent copies them into /drive (or uploads them with ankole-files put). See Worker management for provider storage characteristics.
Common problems
- The Agent cannot find an uploaded file: Share the exact
/drive/...path (or page link) in chat, and verify that the executing Agent holdsviewaccess on that root or folder. On Workers without FUSE, the Agent fetches Drive nodes withankole-files listandankole-files get --node-id. - A generated artifact is missing from Drive: Ask the Agent to copy the file from
/workspaceinto/drive/ChatDrive,/drive/AgentDrive, or/drive/Public, or check whether its Background Agent Job is still running. - Concurrent edit conflict during FUSE writeback: If another writer updates or moves a node before a Worker’s cached write commits (
412or422), inspect/drive-recoveryin that execution scope to recover the preserved draft bytes. - An upload fails with a size limit error: Streaming backends (
fs,s3,gcs,azblob,oss,cos,tos,sftp) follow the backend limit narrowed bydrive.vfs_max_upload_bytes(when non-zero);postgresqlandwebdavcap whole-object uploads at 100 MiB,d1caps single objects at 2,000,000 bytes, and structured Markdown page projections cap at 100 MiB.