Create a world

A world is a whole organization in one YAML file: its departments, the jobs agents can hold and what each job may do, role presets for people, the first agents, and the 3D office they work in. A fresh Agentown install has no world: the admin creates the first one under Create world, from the marketplace or from a file like the one described here.

The file

A world is a YAML mapping of at most 256 KB, with these keys:

Key	What it holds
format	Always agentown.template/v1.
meta	id (lowercase letters, digits and dashes), name (up to 80 characters), description (up to 500), optional term: what the world is called as a whole ("café", "factory").
departments	At least one: { id, name, color }.
projects	Optional: { id, name }.
policyProfiles	Named permission bundles: lists of { action, scope } such as { action: task.create, scope: team }. agent.spawn must list the job templates it may hire.
agentTemplates	The jobs: { id, jobRole, runtimePreset, policyProfile, instructions? }. runtimePreset must be one the install offers (claude-v1 for LLM agents, script-v1 for scripted ones). instructions is how the job is done here (up to 8000 characters): every agent with that job works by it, before its own instructions.
humanRoles	Optional permission presets for people: { name, permissions }.
bootstrap.agents	The first agents: { key, displayName, template, department, reportsTo }.
world	Optional: the office. Without it, every department gets a room on one floor.

The smallest useful world:

format: agentown.template/v1
meta: { id: studio, name: Small studio, description: A producer and an editor. }
departments:
  - { id: crew, name: Crew, color: "#e5484d" }
policyProfiles:
  lead:
    - { action: org.view, scope: org }
    - { action: task.create, scope: team }
    - { action: task.assign, scope: team }
  worker:
    - { action: task.view, scope: self }
agentTemplates:
  - { id: producer-v1, jobRole: producer, runtimePreset: claude-v1, policyProfile: lead }
  - { id: editor-v1, jobRole: editor, runtimePreset: claude-v1, policyProfile: worker }
bootstrap:
  agents:
    - { key: producer, displayName: Vy, template: producer-v1, department: crew }
    - { key: editor, displayName: Sara, template: editor-v1, department: crew, reportsTo: producer }

The office

world describes what people see in 3D:

• floors → rooms: position and size in meters (area: { x, z, w, d }), the department that sits there, floor and wall colors and styles, doors to other rooms on the same floor, and seats to cap the desks in a room.
• links: stairs or elevators between rooms on different floors. zones: named groups of rooms.
• kinds: what things are. A character (a person, cat, dog or robot), static furniture, or dynamic things that spin, bob, pulse, blink, sway, flicker, steam or roam. Looks are built from shapes (box, roundbox, cylinder, sphere, cone, torus, capsule…). Kinds can have states and actions people trigger, an access that says where they may walk, and a title. A few kinds have a job in the office: cleaner: {} is the cleaning robot (it sweeps old leftovers into the trash on a schedule), trash: {} the trash can it empties into, and calendar: {} the wall calendar, which opens the month of every scheduled job (objects doing their actions, tasks for agents, the robot's sweeps). Clicking it lets people put new jobs on it, weekly or once.
• objects: where each kind is placed (room, at: [x, z] inside the room, rotationY).
• chatTemplates: personas by title. Every object with that title can be talked to and answers in that voice.
• avatars: which character each job title looks like.
• theme and style (realistic or anime): the world's colors and drawing style.

The official worlds are full examples: start from the coffee store or the video studio.

Its own art: a world bundle

Shapes in the YAML are enough for a whole office (every official world is drawn that way). For your own pictures and models, make the world a folder:

agentown.world.yaml
assets/        textures (PNG, JPEG, WebP, up to 4 MB) and models (glTF binary .glb, up to 20 MB)
cover.png      the marketplace card's picture (16:9)
screenshots/   more pictures for its page (up to 7)

The world points at its files by path: look: { asset: assets/sofa.glb } on a kind, floorTexture: assets/wood.jpg on a room, image: assets/mocha.png on an object or an avatar. Art is at most 100 MB in all. Each organization made from the world gets its own copy in its art library; the world then points there, and you can change it like any other art.

Try it

In Agentown, open the world switcher at the top and pick + New world, then Upload your world: pick your .yaml file with its art, or the whole folder. The server checks it against the install's runtimes and permissions and tells you what is wrong. Once uploaded, it stays in your templates for the next world. Owners can also save an existing organization as a template under Manage → Organization; its art goes with it as bundle files.

Publish on the marketplace

1. Put the folder at the root of a public GitHub repository: agentown.world.yaml, and assets/, cover.png and screenshots/ beside it if you have them.
2. Add the topic agentown-world to the repository.

The marketplace is rebuilt every 30 minutes. Your world appears as Unverified, pinned to the commit it was read from, with its cover and screenshots on its card; installs download exactly those files and check each one's sha256.

Verified. Open a pull request on agentown-marketplace that adds your repository and the file's sha256 to verified.json:

[{ "repo": "you/your-world", "sha256": "…" }]

Get the sha256 with sha256sum agentown.world.yaml. Only the maintainer merges these after reading the world. A later commit that changes the file drops the badge until it is reviewed again.

Official worlds live in that repository itself: worlds/<id>.yaml, with its folder worlds/<id>/ (assets, cover, screenshots); propose one with a pull request.

What a world can do

A world from someone else is code and instructions you run. Before you use an unverified one, read it for:

• script on kinds: JavaScript that runs in a locked sandbox in each viewer's browser.
• browser.home: web pages its computers open.
• connectors: outside tools (MCP servers) its agents may call.
• Instructions in chatTemplates and agent settings, which shape what agents and personas say and do.

A world never brings API keys, people or permissions beyond what its own file lists, and the server enforces every permission.