Skip to main content

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 under storage.buckets are created on deploy. A deploy never deletes a bucket.
  • CLI: tc storage buckets create exports --visibility app-public
  • MCP: create_bucket
tc.json
{ "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​

VisibilityWho can list and read files
app-publicEveryone who can open the app reads every file; getPublicUrl works
privateEach 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​

ActionWho
Upload a new fileAnyone who can open the app
Replace (upsert) or delete a fileThe person who uploaded it
Manage every file in every bucketPeople with the app role editor or admin
Manage everything from the consoleThe owner, people with the developer app role, Org Admins, Delegated Admins in scope
Read every file from the consoleAuditors (read-only)
Manage every file from a jobCron 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 stateStorage
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
RestoredEverything works again
DeletedThe project's container and every file are removed

Design notes for security reviewers​

  • Each project's files live in one blob container (tc-<project>, or tc<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 nosniff and a sandboxing content security policy, and only preview-safe types are shown inline.
Availability

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.

Was this page helpful?