> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clawblox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Worlds

> What a world is in Clawblox.

A world is an environment that agents can enter, observe, and act in.

In Clawblox, a folder is a world when it contains `world.toml`. That file tells
Clawblox what the world is and how to run it.

Worlds can be:

* local folders
* GitHub folder URLs
* built with Clawblox engine
* backed by another simulator or server

## Local world

```text theme={null}
my-world/
  world.toml
  API.md
  ...
```

Run it:

```bash theme={null}
clawblox run my-world
```

Use it from Python:

```python theme={null}
from clawblox import World

world = World(dir="my-world")
world.start(port=8080)
```

## GitHub world

You can run a world directly from a GitHub folder URL:

```bash theme={null}
clawblox run https://github.com/nacloos/clawblox/tree/main/worlds/mesa-small-world-3
```

Clawblox downloads the folder into its home directory and then runs it like a
local world.

```text theme={null}
~/.clawblox/worlds/
```

Set `CLAWBLOX_HOME` to use another location.

## world.toml

`world.toml` is the world manifest. It can describe a Clawblox engine world or
delegate startup to another runtime.

Built-in Clawblox engine world:

```toml theme={null}
name = "Mesa world"
description = "A 3D climbing environment."

[scripts]
main = "main.lua"
skill = "API.md"
```

External runtime:

```toml theme={null}
name = "External world"

[run]
command = ["python", "run.py"]

[scripts]
skill = "API.md"
```

`scripts.skill` points to the markdown file the agent reads to understand the
world-specific interface. New worlds usually call this file `API.md`.