The full guide is the Cloud Instance section: connecting, what gets set up, the shim, environments and operations. This page is the card-by-card walkthrough.
A space's Cloud is its own Firebase project: once connected, every project created in the space keeps its data there — Firestore, Realtime Database, Storage — instead of in the shared platform cloud. The data is yours in a project that is yours; the platform only holds a credential to it. Projects created before the cloud was connected stay where they are (moving them is a migration the platform runs on request). For the same reason a project that keeps its data in the space's cloud cannot be transferred to another space from the console.
The card sits on the space page (Account → Spaces → the space) and is available on the Business plan of one of the space's projects. Only the space owner can connect, re-check, rotate or disconnect it; admins and members see it read-only.
Connecting with a key#
The first delivery connects a project you already have through a service-account key (a JSON file). Two ways to get one:
| Option | Steps | What to expect |
|---|---|---|
| Console key | Firebase console → Project settings → Service accounts → Generate new private key | The quickest start. The console's default service account is not guaranteed the permissions the checklist needs — when a row fails, the card prints the one gcloud line that grants them (roles/firebase.admin). |
| Dedicated service account | The three gcloud lines on the card: create a service account, grant it roles/firebase.admin, download its key |
Every checklist row passes without further console work. Replace PROJECT_ID with your project id. |
Pick the destination — Europe (Firestore eur3, Realtime Database europe-west1, Storage EU) or United States (nam5 / us-central1 / US); it sets every location at once and cannot change once the Firestore database exists (a project that already has one keeps its own). Then drop the JSON on the card and press Connect. The platform creates whatever the project lacks — the Firestore database, the Realtime Database instance, the default Storage bucket — when the key may (the Realtime Database and the bucket need the Blaze plan; the three APIs must be enabled, and the card prints the gcloud services enable … line when the key cannot do that itself). The key is read in your browser, sent once and dropped; the platform keeps it encrypted in its custody and shows only the service-account e-mail, the project id and the key id afterwards. It never appears in the console, the activity feed or logs.
The checklist#
Connecting runs a probe of what the key can do. The card then shows one row per capability:
| Row | Needed for | If it fails |
|---|---|---|
| Firestore, Realtime Database, Storage | the data itself | blocks — created by the platform when missing (Re-check shows the progress); otherwise grant the role the card prints, then Re-check |
| Indexes & TTL | the platform's composite indexes and cart expiry | blocks — created for you when the key may; otherwise the gcloud firestore … lines are printed |
| Shim heartbeat | the platform learning about writes in your project | blocks until the shim runs — the platform deploys it (below) |
| Shim deploy by platform | the platform deploying the shim for you | needs roles/iam.serviceAccountUser on the key — the card prints the line |
| Large uploads (bucket CORS) | uploading files above 4 MB from the console — the browser sends them straight to your bucket | warning only — the platform adds the upload rule to the bucket's CORS settings itself (your own rules are kept); when the key may not, the card prints the gcloud storage buckets update lines. Until then a large console upload stops with a message pointing here |
| Authentication, Auth config, Web apps, Sign-in providers, Analytics | later features | warnings only |
The project may hold other data: root collections that are not the platform's own (store, stock, promo, payments) are listed on the card and left alone — the platform writes only its own roots, so client-specific collections other systems use can exist before or after connecting.
The shim#
Firebase triggers never cross projects, so something in your project has to forward writes to the platform. That is the shim: six Firestore triggers (Node 22, europe-west1) that forward each written document (both its before and after state) to the platform, signed with a key only your space and the platform share. The platform deploys it for you through the key you uploaded, as soon as the key holds the two roles the checklist names (roles/firebase.admin, roles/iam.serviceAccountUser) and Firestore answers — press Deploy the shim (or just Re-check), wait a few minutes, Re-check. The platform then reads the functions back to prove they run and forward to it; nothing is run on your side, and the shim forwards nothing the platform bills from. The shim key is stored in your project's Secret Manager (or, when the key may not manage secrets, as the function's environment variable — the card says which).
When the platform releases a new shim, the card shows Update the shim; the update runs in the background (a few minutes) and the card refreshes itself when it is done. Deploys are queued and paced, so pressing the button never blocks the page.
Advanced: a client who prefers to deploy the shim themselves can use the drop-core-shim package's CLI under their own Firebase login; ask the platform for the deploy line.
States#
| Chip | Meaning | What you can do |
|---|---|---|
| Not connected | no cloud — projects use the shared cloud | Connect |
| Connecting… | the probe is running | wait |
| Blocked · reason | a required row failed | fix it (the card says how), Re-check, or Disconnect |
| Connected | ready — new projects land in this cloud | Upload a new key (rotation), Re-check, Disconnect (only while no project keeps data there) |
| Unreachable · reason | the key was revoked, lost its permissions, or the project is gone | projects in the space answer 503 org_unreachable until you restore the key or its permissions; Re-check (the platform also re-checks hourly). Tokens, the wallet and the plan are untouched |
One Firebase project serves one environment. The space page shows a PROD Cloud and a DEMO Cloud; a project already connected on one environment is refused on the other (the two would write the same paths, and the shim forwards to one backend only) — use a second Firebase project for Demo, or keep Demo on the shared cloud.
Every new project in the space is created in the cloud when the card reads Connected at that moment — the project wizard's id step says so ("This project will be created in space's own cloud"). Demo: the Demo environment keeps its own binding; without a Demo key the space's Demo projects stay in the shared demo cloud.
Backups#
Backups of the space's projects are not kept in the space's cloud: the platform stores them in its own backup storage in the EU (europe-west1), outside your Firebase project — also for a space whose cloud is in the United States — so a backup never shares storage with the data it protects. Taking a backup reads the project's data and files from your cloud; restoring writes them back there. Deleting a project deletes its backups.
Rotating and revoking#
Upload a new key replaces the credential in place (same project); delete the old key in Google Cloud IAM afterwards — the card shows its id. Disconnect removes the key and the shim key from the platform's custody and stops nothing in your project; it is refused while a project of the space still keeps data in the cloud. You can revoke the platform's access at any time from your IAM page: the space then reads Unreachable and its projects answer 503 until access is restored.
Coming later: connecting through an IAM grant to the platform's service account, a project hosted by inmake on request, and Create it for me — a one-consent bootstrap that creates and configures the project in your Google account.