Buckets

Create a storage bucket inside an environment, name it, and choose whether its objects are served publicly.

A bucket is the container objects live in, and it belongs to exactly one environment. Create one before your first upload, from the console, from the API, or declaratively in gigadrive.yaml.

Creating a bucket

In the console, open the environment, select File Storage, then Create Bucket. The dialog asks for a name and a visibility; Gigadrive Network fills in the rest.

import { GigadriveClient } from '@gigadrive/sdk';

// clientId and clientSecret fall back to GIGADRIVE_CLIENT_ID and GIGADRIVE_CLIENT_SECRET
const client = new GigadriveClient({
  applicationId: '0197b2f1-2f4a-7a0b-8a2d-222222222222',
});

const bucket = await client.storage.buckets.create({
  name: 'user-uploads',
  environment: 'production',
  visibility: 'public',
});

console.log(bucket.slug, bucket.cdnHostname);

The token comes from the client-credentials flow described in Authentication, and needs the network:storage_buckets:write scope. environment takes a slug or a UUID; credentials issued to a running deployment already know their environment and reject a value that disagrees with it.

Two identifiers

The response carries both. They are not interchangeable.

Field	What it is	Where you use it
`name`	Immutable, unique within the environment	REST, the SDK, `gigadrive.yaml`
`slug`	Globally unique DNS label, generated from the name	The delivery hostname, and the bucket name an S3 client sends

The slug is built by taking the name, cutting it to 54 characters and appending a random 8 character suffix. A bucket named user-uploads gets a slug such as user-uploads-k7qm4ztb and the hostname user-uploads-k7qm4ztb.public.gigadriveuserstorage.com.

Naming rules

A name is stored exactly as you send it. One that breaks a rule is rejected with a 400 rather than corrected, so User_Uploads fails instead of arriving as user-uploads.

Rule	Value
Length	3 to 63 characters
Characters	Lowercase letters, digits, and hyphens between them
Shape	Cannot look like a UUID, which is reserved for the deprecated bucket reference
Uniqueness	Unique inside the environment, so two environments can both hold `uploads`

Public and private buckets

Visibility decides how an object is read, and nothing else. A public bucket answers https://<slug>.public.gigadriveuserstorage.com/<key> for anyone who has the URL. A private bucket answers only a signed URL with a token and an expiry, which you mint per object. Both are covered in Access URLs.

New buckets are private unless you ask for public.

Visibility is fixed at creation

No console control, REST route or SDK method changes a bucket's visibility afterwards, and the public or private label is baked into the delivery hostname. If you need the other policy, create a second bucket.

Declaring buckets in gigadrive.yaml

Buckets listed under services.storage are provisioned into the deployment's environment during the build.

services:
  storage:
    buckets:
      assets:
        visibility: public
      uploads: null

null or an empty object accepts the default private visibility. Provisioning is additive: a name that already exists is reused untouched, including its visibility, and a bucket you stop declaring is never deleted. The build log records the outcome as Provisioned 2 File Storage bucket(s) (1 created, 1 existing). A deployment that declares buckets without an environment fails.

Buckets per environment

The limit comes from the organization's plan, and it is counted against the environment you are creating the bucket in. A full production environment therefore does not block the first bucket in a preview one.

Plan	Buckets per environment
Starter	5
Pro	50
Enterprise	No limit

Going over returns Storage buckets per environment quota reached (5/5). Contact support to request a limit increase.

Deleting a bucket

A bucket has to be empty first. Delete every live object, then delete the bucket; objects sitting in trash are purged as part of the delete and do not block it. A bucket that still has backups is refused as well, because a backup keeps files alive that the bucket itself no longer holds. Delete those backups, then the bucket.