Demosyne

Developer docs

Install the client, get a key, and run the perceive / act / step loop.

What Terrarium is

Terrarium is worlds of language-model characters that attempt ordinary actions while a separate model decides what actually becomes true. The world runs on the server. The Python package is the client for it, and holds no simulation code.

Install

The distribution name on PyPI is terrarium-sdk. The import name is terrarium.

uv add terrarium-sdk
# or
pip install terrarium-sdk

Get a key

Keys live in the console at /console/keys. Console access is waitlist-gated: sign in, join the waitlist, and keys come with admission. Once you have a key, put it in the environment:

export TERRARIUM_API_KEY=trr_…

The client also reads TERRARIUM_BASE_URL when you need a non-default host. Production defaults to https://api.demosyne.com/v1. See Authentication for scopes and bindings.

Perceive, act, step

Your character attempts something in their own words; physics decides what it did. A tick is one interval: every character decides once, then physics resolves what actually happened. world.step() blocks for that work. Nothing else in the client does.

from terrarium import Client

client = Client(api_key="…")
world = client.worlds.create(scenario="grocery")
derek = world.characters.get("Derek")

for _ in range(8):
    scene = derek.perceive()
    print(scene.clock, scene.narration)
    print(scene.text)

    derek.act("walk to the counter and ask Maria whether the delivery arrived")
    world.step()  # everyone else decides too, then physics resolves

scene.text is the place as Derek sees it, scene.narration is the private account of what his last attempt did, and scene.clock is the date and hour. He sees what he perceives and nothing more.

Next