SDK recipes

Each recipe starts with a working connection and shows the same job in TypeScript and Python. Copy a program, set the environment variables, and run it against a SoulFire server.

Before you startCopy Anchor Link

Complete the matching SDK installation and one first-program tutorial. These recipes attach to saved accounts on an existing backend. Use named setup and ID discovery to obtain the identifiers below. For automatic local setup, use the managed first program instead.

Python requires CPython 3.14 or newer. Set these values for every recipe:

export SOULFIRE_URL="https://soulfire.example.com"
export SOULFIRE_TOKEN="your-api-token"
export SOULFIRE_INSTANCE_ID="your-instance-uuid"
export SOULFIRE_BOT_ID="your-bot-uuid"

The recipes use TypeScript Effect v4 and Python effect-py. See the TypeScript guide or Python guide for runtime setup and scoped cleanup.

Pick a jobCopy Anchor Link

• Reply to chat when a player sends a message.
• Collect blocks and wait for the durable task to finish.
• Follow the entity under the cursor with a connection safe reference.
• Move items through a container and close the menu safely.

Run and stop a recipeCopy Anchor Link

Save the code using the filename in its code block. Run a TypeScript file with bun run <filename.ts>. Run a Python file with your virtual environment's Python, such as .venv/bin/python <filename.py>.

Read the recipe's prerequisites and expected result before starting it. Continuous recipes run until interrupted. Finite recipes finish after their action or task completes. Recipes that use bot.connect() stop bots they start when the scope closes. Already-running bots remain running. The follow recipe uses the lower-level start API so its detached task can continue after the program exits. Cancel detached tasks and stop their bots explicitly when that work must end. See bot state and task ownership.