Atmosphere in a Box #

While doing heavy development which required multiple PDS I realized I was effectively polluting plc.directory with all the dids I was minting. I also had to deal with headaches of serving ssl via tunnels and the odd dns names I'd get as a consequence then try and remember what rabbit-cabbage-water was for or deal with passing tokens in every request to bypass security guards.

As a consequence of this, I ended up building a small local environment that allowed me to run a PLC directory with however many PDS I needed with SSL. I could now do whatever work was needed including oauth requests that weren't always pointing to localhost.

This Setup is effectively:

• CoreDNS for friendly names
• Caddy TLS for SSL deliciousness
• PLC Directory for DID funsies

The default setup will provide you with one or more PDS instances as you need with the following changes:

• SSRF protection disabled as PDS OAuth SSRF protection inspects for and blocks private addresses. See OAuth SSRF Testing for details.
• No rate limitings
• no invite code required

It supports adding arbitrary services on top which you are developing locally, see USAGE for details on how to define them.

Quickstart #

Check that 172.30.249.0/24 does not overlap your host, VPN, or Docker networks. Install Deno 2.8, Docker Compose with --wait support, then run:

deno task install
deno task sandbox create --pds 3 --users-per-pds 2
deno task sandbox check
deno task sandbox up --build
deno task sandbox seed
deno task sandbox smoke

This creates pds1 through pds3, each with user1 and user2. Credentials and DIDs are private files under state/. Stop the sandbox without discarding data with deno task sandbox down.

Where next? #

• Operate or change a sandbox
• Add an included application
• Develop the sandbox itself
• Network and client trust
• Verified CI connection example
• Safety, recovery, and reset

Important limits #

The sandbox has no published host ports by default. The only exception is the explicit sandbox access start relay, which binds only 127.0.0.1:443 and still requires manual hostname and certificate-trust setup. Clients inside it use sandbox DNS and the read-only public CA.