---
title: setWorld
description: Override or reset the cached World instance used by the workflow runtime.
docs_index: /llms.txt
lastUpdated: 2026-10-21
type: reference
summary: Use setWorld to inject a custom World instance or reset the cache to the build-injected World.
prerequisites:
  - /docs/api-reference/workflow-runtime/get-world
related:
  - /docs/api-reference/workflow-runtime/create-world
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

Overrides the cached [World](/docs/api-reference/workflow-runtime/world) instance that [`getWorld()`](/docs/api-reference/workflow-runtime/get-world) returns. Use it to inject a World constructed with explicit configuration, or pass `undefined` to clear the cache so the next `getWorld()` call reconstructs the World that was statically injected into the bundle at build time.

```typescript lineNumbers
import { setWorld, getWorld } from "workflow/runtime";
import type { World } from "@workflow/world";
declare const customWorld: World; // @setup

setWorld(customWorld); // [!code highlight]
const world = await getWorld(); // resolves customWorld
```

## API signature

### Parameters

| Parameter | Type                 | Description                                                                                                           |
| --------- | -------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `world`   | `World \| undefined` | The World instance to use, or `undefined` to reset the cache so the next access reconstructs the build-injected World |

### Returns

This function does not return a value.

## Example: inject a specific World

The build selects the target World via `WORKFLOW_TARGET_WORLD` and statically injects it into the bundle. Changing the environment variable at runtime has no effect. To use a different World at runtime, construct it explicitly with the World package's `createWorld()` factory and inject it:

```typescript lineNumbers
import { setWorld } from "workflow/runtime";
import { createWorld } from "@workflow/world-local";

setWorld(createWorld({ dataDir: "/tmp/workflow-test" })); // [!code highlight]
```

Calling `setWorld(undefined)` afterwards restores the build-injected World on the next `getWorld()` call.

## Related functions

- [`getWorld()`](/docs/api-reference/workflow-runtime/get-world): Resolve the cached World instance.
- [`createWorld()`](/docs/api-reference/workflow-runtime/create-world): Construct a fresh instance of the build-injected World.

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)