Context: My team and I were trialing / piloting spicedb locally in order to test and de-risk for a larger integration with our app. Several of us use Orbstack instead of Docker Desktop.

Initially, our pilot was derailed by several engineers unable to identify why the @authzed/authzed-node client could not connect.

A question and its answers in Discord channel put our pilot back on track. The key was to connect to local orbstack docker container with INSECURE_PLAINTEXT_CREDENTIALS instead of INSECURE_LOCALHOST_ALLOWED. By default, Orbstack creates a set of *.orb.local hostnames each of its containers, including e.g. spicedb.app.orb.local.

Since we were not running the spicedb container on "localhost", the INSECURE_LOCALHOST_ALLOWED setting that in most documentation we found was not the appropriate setting.

I think it would be very beneficial to future visitors to add v1.ClientSecurity.INSECURE_PLAINTEXT_CREDENTIALS as the default security setting for documentation that is meant for developers who are trialing spicedb locally.

The critical point is that although "INSECURE_LOCALHOST_ALLOWED" may appear to self-document that it is for localhost only, there are so many variables in an initial docker setup and pilot code, that it is not obvious to newcomers that this is the key piece.