Files
Upload, download, and delete workspace-scoped files via presigned object storage URLs.
Files stores workspace-scoped objects in S3-compatible storage (MinIO locally, S3/R2/GCS in production). Uploads go directly to the bucket via presigned URLs — bytes do not proxy through Control Plane.
Who can access
| Action | Required permission |
|---|---|
| List / download files | read |
| Upload files | write |
| Delete files | delete |
Prerequisites
- Workspace selected in the top navigation picker
- Object store configured for the environment
Upload a file
Open Files
In the sidebar under Data, click Files.
Click Upload
Click Upload and select a file from your computer.
Wait for completion
The portal requests a presigned PUT URL, uploads directly to storage, then finalizes the file record. A success toast confirms when done.
The file appears in the table with name, size, content type, and upload date.
Download a file
Click the Download icon on a file row. The browser opens a presigned download URL.
Delete a file
Click Delete
Click the trash icon on the file row.
Confirm
Confirm in the dialog. Deletion removes the object from storage and the metadata row.
File table
Columns include Name (with mime-type icon), Size, Content type, Uploaded by, and Created. Files stuck in pending state are cleaned up automatically if upload never completes.
Large files upload directly to the bucket. Ensure your network allows PUT requests to the storage endpoint (no corporate proxy blocking presigned URLs).
Troubleshooting
| Problem | Likely cause | What to do |
|---|---|---|
| Upload fails at finalize | Object never reached bucket | Retry upload; check browser network tab for PUT errors |
| File stuck pending | Abandoned upload | Wait for hourly cleanup or delete manually |
| Download 403 | Expired presigned URL | Click download again for a fresh URL |
| Empty file list | Wrong workspace | Check workspace picker |
Related API
GET /v1/workspaces/{id}/files— list filesPOST /v1/workspaces/{id}/files/upload-url— request presigned PUTPOST /v1/workspaces/{id}/files/{file_id}/finalize— finalize uploadGET /v1/workspaces/{id}/files/{file_id}/download-url— presigned GET
See Shell Files for programmatic upload from federated apps.