v0.4.0 · Apache-2.0

Install CloudBurrow.

Releases are published for macOS and Linux on arm64 and amd64. The installer checks each archive against its SHA-256 checksum. It can also verify the build attestation when the GitHub CLI is available.

Local setup

From the first check to an SDK call.

Check the engine, install the release and start an instance. Then point a separate shell at the local services.

  • Check your container engine and prerequisites.
  • Install the pinned release and verify your setup.
  • Make a local Cloud Storage call from an SDK.
Check and start
cloudburrow doctorcloudburrow up
Connect a second shell
eval "$(cloudburrow env)"
Inside local setup

Go straight to the detail you need.

1Before you install

Docker, kind v0.33.0 and kubectl. Go only if you build from source. Give Docker at least 4 CPU and 6 GB; the full stack measures about 1.5 GiB and 2.1 CPU.

StatusEngines
Supported Docker Desktop on macOS; rootful Docker Engine on Linux
Unverified colima, OrbStack, Rancher Desktop
Unsupported Podman, rootless Docker

Windows is unsupported; WSL2 is untested. Container engines, with the evidence for each

2Install

Homebrew

Homebrew
brew install cloudburrow/tap/cloudburrowcloudburrow version

Install script

Install script
curl -fsSL https://raw.githubusercontent.com/cloudburrow/cloudburrow/main/scripts/install.sh | sh

It verifies the SHA-256 checksum and, when gh is installed, the GitHub build attestation. It refuses an archive it cannot verify.

From source

From source
git clone https://github.com/cloudburrow/cloudburrow.gitcd cloudburrowmake build

A plain go install build has no embedded Storage server, and up refuses it. Use make build.

Needs Docker (4 CPU / 6 GB), kind v0.33.0 and kubectl. macOS and Linux only; Windows is unsupported and WSL2 is untested. macOS binaries in v0.4.0 are signed with a Developer ID and notarized by Apple. The console opens at http://127.0.0.1:9090 and is labelled LOCAL.

The v0.4.0 macOS binaries are signed with a Developer ID and notarized by Apple. See Gatekeeper in docs/install.md.

3Check

cloudburrow doctor changes nothing, and fails only on what would stop up. It also checks the ports for the selected services and reports the offline cache state when asked to run offline.

cloudburrow doctor
cloudburrow doctor  ok      docker                   /usr/local/bin/docker  ok      kind                     /opt/homebrew/bin/kind (v0.33.0)  ok      kubectl                  /usr/local/bin/kubectl  ok      docker daemon            29.8.0 (Docker Desktop)  ok      docker engine            Docker Desktop (in a VM)  ok      docker memory            39.1 GiB  ok      docker cpus              16  ok      disk space               24.2 GiB free on ~ (the host volume backing                                   the Docker Desktop VM disk, not the VM filesystem)  ok      port control             127.0.0.1:9000 is free  ...All checks passed.
Sample output from docs/install.md
ok
Passed.
warn
Will probably work: an untested kind release, or disk below the 20 GiB margin.
FAIL
up will not succeed. Exit code 1. Only FAIL blocks.
unknown
Could not be measured. Deliberately not ok, and does not block.

4Run

cloudburrow up
cloudburrow up

In another shell, point Google tooling at it:

Another shell
eval "$(cloudburrow env)"

That exports endpoint overrides, the project, a local metadata server and a generated ADC file. The credentials authorise nothing; they exist so tooling that insists on them runs offline.

stop, reset and delete are distinct commands, and none implies another.

5Make your first call

Python · Cloud Storage
import uuid
from google.cloud import storage

client = storage.Client()
bucket = client.create_bucket(f"example-{uuid.uuid4().hex[:12]}")
bucket.blob("hello.txt").upload_from_string("hello")
assert bucket.blob("hello.txt").download_as_text() == "hello"
bucket.delete(force=True)

This block is run by CloudBurrow's Python suite in CI. If it stops working, CI fails. docs/examples/python.md

Node.js · Cloud Storage
import assert from 'node:assert/strict';
import { randomUUID } from 'node:crypto';
import { Storage } from '@google-cloud/storage';
import { PassThroughClient } from 'google-auth-library';

const apiEndpoint = process.env.STORAGE_EMULATOR_HOST;
delete process.env.STORAGE_EMULATOR_HOST;
const storage = new Storage({
  apiEndpoint,
  projectId: process.env.GOOGLE_CLOUD_PROJECT,
  authClient: new PassThroughClient(),
});

const [bucket] = await storage.createBucket(`example-${randomUUID()}`);
await bucket.file('hello.txt').save('hello', { resumable: false });
const [data] = await bucket.file('hello.txt').download();
assert.equal(data.toString(), 'hello');
await bucket.deleteFiles({ force: true });
await bucket.delete();

This block is run by CloudBurrow's Node.js suite in CI. If it stops working, CI fails. docs/examples/node.md

Go is tested through CloudBurrow's own compatibility suite. Java, .NET, Ruby and PHP are untested (#718).

6gcloud and Terraform

cloudburrow gcloud-setup configures the Google Cloud CLI. The compatibility notes list verified commands for storage, KMS, secrets, tasks, scheduler, logging, projects and Pub/Sub. Named tests also exercise selected Cloud Run service and job commands, local source deploys, Service Usage, gcloud iam roles and service accounts, gcloud sql, gcloud redis and gcloud memorystore.

cloudburrow terraform sets local endpoints for the supported provider resources. Check the per-resource coverage before applying a configuration. Verified with Terraform's hashicorp/google 8.4.0 and OpenTofu 1.12.6.

Every tool and the test behind it, in docs/status.md

7How long does up take?

One measured run on Ubuntu, 2026-09-24: the default profile started cold in 85 s and warm in 30 s. It is a single measurement, not a benchmark.

Source: Footprint, in docs/status.md

8Offline

cloudburrow prefetch downloads what up needs; up --offline then runs without a network.

Offline start Run cloudburrow prefetch while online to download what up needs, then cloudburrow up --offline runs without a network. Since v0.3.0 online cloudburrow prefetch what up needs no network cloudburrow up --offline

Offline and air-gapped use, in docs/install.md

Develop locally

Build against Google Cloud APIs, locally

Free and open source under Apache-2.0. No account, no sign-up, no Google Cloud bill.