Integrating cloudemu

Integrating cloudemu means your app's real code path runs against it: you point your existing cloud client at a running cloudemu and exercise the actual request flow end to end.

The pattern: run cloudemu in server mode and point your app's existing cloud client at it by overriding one endpoint. Your real code runs, unchanged, against an in-memory cloud — no mocks. This is how you wire cloudemu into an existing service, and it exercises the real request path end to end.

1. Run cloudemu in server mode#

cloudemu serve      # or: docker run --rm -p 4566:4566 ghcr.io/stackshy/cloudemu:latest

It prints the live endpoints — AWS http://127.0.0.1:4566, Azure https://127.0.0.1:4568, GCP http://127.0.0.1:4569. See Standalone Server for ports, flags, and cloudemu env.

2. Make the endpoint injectable#

Point your app's client at cloudemu by overriding one endpoint. Make it injectable so production uses the real cloud and dev/tests use cloudemu — your code doesn't change. An env var is the easy default (shown below), but a config field works just as well.

return s3.NewFromConfig(cfg, func(o *s3.Options) {
    if ep := os.Getenv("AWS_ENDPOINT_URL"); ep != "" {
        o.BaseEndpoint = aws.String(ep) // set → cloudemu; unset → real AWS
        o.UsePathStyle = true
    }
})

Now start your service (or CLI) with the endpoint pointed at the running cloudemu, and every call hits the in-memory backend:

export AWS_ENDPOINT_URL=http://127.0.0.1:4566
./your-app                    # your real service, talking to cloudemu

The endpoint knob, per SDK#

Every SDK exposes a way to override the service endpoint. That override is the only change your app needs:

Not writing Go? The standalone server speaks the same wire protocols — set AWS_ENDPOINT_URL (or --endpoint-url on the CLI) and any SDK in any language points at it.

Go test suites: in-process instead of a separate process#

If you're writing Go tests and would rather not manage a separate process, stand cloudemu up inside the test with httptest and point the same injectable endpoint at it. This is the in-process convenience for Go test suites — for integrating a running service, prefer server mode above.

func startCloudEmu(t *testing.T) {
    srv := awsserver.New(awsserver.Drivers{S3: cloudemu.NewAWS().S3})
    ts := httptest.NewServer(srv)
    t.Cleanup(ts.Close)
    t.Setenv("AWS_ENDPOINT_URL", ts.URL) // same knob your app already reads
}

Keep cloudemu in _test.go only — never import it from production code.

Tell your AI agent#

Wiring cloudemu into an existing service with an assistant? Paste this into your repo's AGENTS.md so it integrates cloudemu the right way — by pointing your running service at it:

cloudemu (github.com/stackshy/cloudemu/v2) is a standalone, in-memory cloud emulator.
To integrate it with THIS service: run it as a server
(`docker run -p 4566:4566 -p 4568:4568 -p 4569:4569 ghcr.io/stackshy/cloudemu`, or
`cloudemu serve`) and point the RUNNING service's SDK at its endpoint. Override the
endpoint however this codebase configures its clients: AWS AWS_ENDPOINT_URL env or
o.BaseEndpoint, GCP option.WithEndpoint(...) + option.WithoutAuthentication(), Azure
ARM endpoint/host override, Databricks Config.Host. Your real code path then hits
cloudemu end-to-end; production points at the real cloud with the same code. cloudemu
is a dev/test dependency, used only outside production.