Storage
Every project can store files in buckets: receipts, exports, images, PDFs. Files are served from the app's own origin under /_tc/storage/*, always behind company sign-in, and the SDK's API is shaped like Supabase's storage client.
Buckets
A bucket is a named folder of files with a visibility. Create buckets in any of these ways:
- Console: the project's Storage page, New bucket (name, visibility, read roles).
tc.json: buckets listed understorage.bucketsare created on deploy. A deploy never deletes a bucket.- CLI:
tc storage buckets create exports --visibility app-public - MCP:
create_bucket
{ "storage": { "buckets": {
"receipts": { "visibility": "private", "readRoles": ["approver"] },
"exports": "app-public"
} } }
Bucket names are 3–63 characters: lowercase letters, digits and dashes, starting and ending with a letter or digit, without --. sign, public, list, info, upload and internal are reserved.
Visibility
| Visibility | Who can list and read files |
|---|---|
app-public | Everyone who can open the app reads every file; getPublicUrl works |
private | Each person reads their own files; app roles in readRoles read every file; anyone else needs a signed URL |
There is no internet-public option. Even an app-public bucket is only reachable by people who are signed in and allowed to open the app.
Who can do what
| Action | Who |
|---|---|
| Upload a new file | Anyone who can open the app |
Replace (upsert) or delete a file | The person who uploaded it |
| Manage every file in every bucket | People with the app role editor or admin |
| Manage everything from the console | The owner, people with the developer app role, Org Admins, Delegated Admins in scope |
| Read every file from the console | Auditors (read-only) |
| Manage every file from a job | Cron and worker services (they act as the app) |
The uploader is recorded with each file. Uploads and deletes are audited (storage.upload, storage.delete).
The Storage page
The project's Storage page shows:
- Buckets with their visibility, file count and size.
- A file browser: folders by path prefix, breadcrumbs, a filter, drag-and-drop upload with progress, previews of images, PDFs and text, download, delete, and copy a signed link (valid for one hour).
- A usage bar against the project quota, with a monthly cost estimate.
- Bucket settings: change visibility, or delete the bucket (with confirmation). Deleting a bucket removes its files in the background.
- Quota: Org Admins can change the project's quota and per-file limit. See Quotas and limits.
Lifecycle
| Project state | Storage |
|---|---|
| Archived | /_tc/storage answers PROJECT_ARCHIVED; files are kept; the console can browse read-only |
| Disabled by IT | /_tc/storage answers PROJECT_DISABLED; files are kept |
| Restored | Everything works again |
| Deleted | The project's container and every file are removed |
Design notes for security reviewers
- Each project's files live in one blob container (
tc-<project>, ortc<tenant>-<project>for an organization on vastframe cloud), and a bucket is the first path segment. This keeps container names collision-free and lets access be scoped to one project's container. - A dedicated storage service holds the only blob credential; neither apps nor the Integration Gateway have it.
- Content types are checked against the file's bytes, and HTML, SVG, scripts and executables are refused, because files are served from the app's origin. Downloads are sent with
nosniffand a sandboxing content security policy, and only preview-safe types are shown inline.
On the local stack storage runs on Azurite, Microsoft's Azure Storage emulator, through the same Azure SDK driver that talks to a real storage account. Managed-identity authentication to Azure Storage, private endpoints and Key Vault for the signing secret are coming soon.