> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tembo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Cloud Storage

> Configure Google Cloud Storage for Tembo self-hosted on Google Cloud.

Tembo can use a Google Cloud Storage bucket as a single store for file uploads and VM snapshots. If you skip this configuration, file uploads are unavailable and sandboxes start more slowly.

***

## Step 1: Create a Bucket

### Via the Google Cloud CLI

```bash theme={null}
gcloud storage buckets create gs://<bucket-name> \
  --project=<your-project-id> \
  --location=us-central1 \
  --uniform-bucket-level-access
```

Use the same region as your Tembo VM.

### Via the Google Cloud console

1. Go to **Cloud Storage > Buckets** and select **Create**
2. Enter a **Name** (globally unique)
3. Under **Location type**, select **Region** and choose the region of your Tembo VM
4. Leave **Uniform** access control selected and leave all other settings as default
5. Select **Create**

***

## Step 2: Create a Service Account and Key

Tembo signs browser upload and download URLs with a service account key, so the key is required even if your VM has an attached service account.

### Via the Google Cloud CLI

```bash theme={null}
# Create the service account
gcloud iam service-accounts create tembo-storage \
  --project=<your-project-id> \
  --display-name="Tembo storage"

# Grant it read/write access to the bucket
gcloud storage buckets add-iam-policy-binding gs://<bucket-name> \
  --member="serviceAccount:tembo-storage@<your-project-id>.iam.gserviceaccount.com" \
  --role="roles/storage.objectAdmin"

# Create a JSON key
gcloud iam service-accounts keys create tembo-storage-key.json \
  --iam-account=tembo-storage@<your-project-id>.iam.gserviceaccount.com
```

### Via the Google Cloud console

1. Go to **IAM & Admin > Service Accounts** and select **Create service account**
2. Enter a name (for example, `tembo-storage`) and select **Done**
3. Go to **Cloud Storage > Buckets**, open your bucket, and select the **Permissions** tab
4. Select **Grant access**, enter the service account email, choose the **Storage Object Admin** role, and select **Save**
5. Go back to **IAM & Admin > Service Accounts**, open the service account, and select the **Keys** tab
6. Select **Add key > Create new key**, choose **JSON**, and select **Create**

The key file downloads to your machine. You need its `client_email` and `private_key` values in Step 4. Delete the file after you copy them.

> [!NOTE]
>
> If your organization policy blocks service account key creation (`iam.disableServiceAccountKeyCreation`), ask your Google Cloud administrator for an exception for this project.

***

## Step 3: Configure CORS

Tembo uploads image attachments directly from the browser to Cloud Storage. Cloud Storage blocks these cross-origin requests by default, so you must add a CORS rule.

Save the following as `cors.json`:

```json theme={null}
[
  {
    "origin": ["http://<vm-external-ip>"],
    "method": ["GET", "HEAD", "PUT"],
    "responseHeader": ["Content-Type", "x-goog-content-sha256"],
    "maxAgeSeconds": 3600
  }
]
```

If you are using a custom domain, replace `http://<vm-external-ip>` with your domain.

Apply it to the bucket:

```bash theme={null}
gcloud storage buckets update gs://<bucket-name> --cors-file=cors.json
```

***

## Step 4: Add to config.json

Open `/var/lib/tembo/config.json` (via the VS Code server at `http://<vm-external-ip>:8888` or SSH) and add:

```json theme={null}
{
  "selfHosted.objectStorage.provider": "gcs",
  "selfHosted.objectStorage.bucket": "<bucket-name>",
  "selfHosted.objectStorage.gcs.projectId": "<your-project-id>",
  "selfHosted.objectStorage.gcs.clientEmail": "<client_email from the key file>",
  "selfHosted.objectStorage.gcs.privateKey": "<private_key from the key file>"
}
```

Copy `private_key` exactly as it appears in the key file, including the `-----BEGIN PRIVATE KEY-----` line and the `\n` sequences.

> [!TIP]
>
> You can also enter these values under **Settings → Self-hosted → Object storage** on your instance, then select **Restart Services**.

Then restart all Tembo services:

```bash theme={null}
sudo systemctl restart 'tembo-ts-*'
```

Restarting only the API is not enough. Agent workers and the VM manager handle VM snapshots and read `config.json` only when they start.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.