Storage — Nubes Docs

Declare storage

nubes.hcl

version = 1

storage "uploads" {}

app "api" {
  source "nodejs" {
    path = "./api"
  }

  env = {
    STORAGE_BUCKET            = storage.uploads.bucket
    STORAGE_ENDPOINT          = storage.uploads.endpoint
    STORAGE_REGION            = storage.uploads.region
    STORAGE_ACCESS_KEY_ID     = storage.uploads.access_key_id
    STORAGE_SECRET_ACCESS_KEY = storage.uploads.secret_access_key
  }
}

Each storage declaration provisions a private bucket isolated by organization, project, environment, and resource name. Your app uses its own S3-compatible client to upload, list, download, and delete objects. Choose environment variable names that match your app.

Nubes stores credentials in WorkOS Vault. Both credential outputs are treated as secrets; deployment plans and history contain only Vault references. Only apps that explicitly reference a credential receive it, during deployment. Keep these credentials on your app’s server. Your app can issue presigned URLs for browser uploads and downloads and is responsible for checking its users’ permissions.

The credentials allow object operations in the declared bucket. They do not grant bucket administration or access to other buckets.

Redeployments and retention

Redeploying the same declaration reuses its bucket and saved credentials. Changing the provider account configuration affects new storage declarations; existing declarations retain their saved endpoint and credentials. Renaming a declaration creates a different bucket and does not move files.

Removing a declaration does not delete its bucket or revoke credentials. Automatic deletion, migration, credential rotation, storage usage billing, public hosting, and lifecycle rules are not implemented. Retain and manage existing data explicitly through the provider.

Provider configuration

HCL and the deployment workflow use a provider-neutral S3 contract. The initial provider adapter is Cloudflare R2. Configure these environment variables on the Convex backend:

NUBES_STORAGE_PROVIDER_MODE=r2
NUBES_STORAGE_R2_ACCOUNT_ID: the Cloudflare account with R2 enabled.
NUBES_STORAGE_R2_API_TOKEN: a management token authorized for Workers R2 Storage Write and Account API Tokens Write in that account.
WORKOS_API_KEY: a WorkOS key with Vault access.

The adapter creates default-jurisdiction private buckets and account-owned, bucket-scoped object read/write tokens. The management token is never supplied to apps. R2 uses auto as its S3 region. New credentials have no configured expiration.

NUBES_STORAGE_PROVIDER_MODE=mock provides deterministic test references without creating a usable bucket. Use it only for local development and tests.

For provider implementations, see the StorageProvider interface in the backend storage module. Account credentials and provider permission formats belong in adapters; the deployment workflow consumes only bucket, endpoint, region, and a Vault object reference.