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

terrarium-sdk is source-installed and is not published to a package registry. Clone the repository and run the installer from that checkout. The package still imports as terrarium.

git clone https://github.com/demosyne/terrarium.git
cd terrarium
./install.sh

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() queues one tick and waits for its durable job to finish.

from terrarium import Terrarium

with Terrarium() as client:
    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