SDK versions and installation

The examples use SoulFire SDK 2.10.2. The TypeScript SDK requires Effect v4. The Python SDK requires CPython 3.14 or newer and uses effect-py. Both packages are available from their package registries.

Install the TypeScript SDKCopy Anchor Link

Create an application with Bun:

mkdir soulfire-tutorial
cd soulfire-tutorial
bun init -y
bun add @soulfiremc/sdk@2.10.2 effect@^4

For Node.js 22 or newer, install the Node runtime too:

npm install @soulfiremc/sdk@2.10.2 effect@^4 @effect/platform-node@^4
npm install --save-dev tsx

Choose the entry point for your application:

The universal entry point connects to an existing backend. connectWithHttpClient and layerWithHttpClient accept the Effect v4 effect/http/HttpClient service. The Node, browser, and Bun entry points supply their HTTP layer. Effect v4 includes portable HTTP modules. These examples do not require @effect/platform.

Continue with your first TypeScript program.

Install the Python SDKCopy Anchor Link

Create a virtual environment with CPython 3.14 or newer:

mkdir soulfire-python-tutorial
cd soulfire-python-tutorial
python3.14 -m venv .venv
.venv/bin/python -m pip install soulfire==2.10.2

On Windows, use py -3.14 -m venv .venv and .venv\Scripts\python for the remaining commands. The SDK installs effect-python==0.1.0a2, which provides the effect_py module, and its RPC dependencies. Keep that pinned effect-py version when using this SDK release.

Continue with your first Python program.

Choose a backendCopy Anchor Link

For a local script, SoulFire.createBot or Python SoulFire.create_bot downloads SoulFire and Java when needed. It creates or reuses the instance and account, starts the bot, and waits for its initial player snapshot. The tutorials pin the managed backend with installation.version or Python installation={"version": "2.10.2"}. Without a version, managed installation selects the latest release.

For an existing backend, use SoulFire.connect with its API URL and token. The handshake checks API versions, capabilities, and required plugins. Named instance provisioning requires the instance.provisioning.v1 capability. See named setup and existing bots.

Check the installed versionCopy Anchor Link

TypeScript:

bun pm ls

Python:

.venv/bin/python -c "from importlib.metadata import version; print(version('soulfire'))"

Expect SDK version 2.10.2. A matching version label alone does not prove backend compatibility. The backend must also pass the connection handshake.

Migrate older applicationsCopy Anchor Link

The TypeScript high-level API uses Effect operations, streams, and scopes. Compose calls with yield* inside Effect.gen and run the complete workflow once at the application boundary. Use Effect v4 imports such as effect/http/FetchHttpClient instead of Effect v3 platform modules.

The Python high-level API uses lazy effects instead of the older async/sync client API. Compose calls with yield from inside @gen or @fn. Run the workflow with run_async(scoped(program).or_die()) at the application boundary. Stream callbacks return effects; consumers use run_for_each, run_collect, or other effect-based operations. Generated protocol clients remain available for direct transport integration. Read the TypeScript runtime and Python runtime guides for details.

Source and generated referenceCopy Anchor Link

The documentation uses the 2.10.2 release source. The node reference links to that revision. The TypeScript API and Python API show their SDK version and source. The HTTP schema reports its own version and covers unary JSON operations. The connected backend's metadata and node palette describe its installed capabilities.

For SDK development, clone the same revision, run bun install --frozen-lockfile, and build from sdk/typescript. For a Python source install, use:

.venv/bin/python -m pip install "soulfire @ git+https://github.com/soulfiremc-com/SoulFire.git@878ba24b85ee4a1ec170ed738b7664b61ace1a2d#subdirectory=sdk/python"