Skip to main content
ancha world gen writes a world from a description. A model invents the company, its people and the history in each tool. Ancha turns the answer into a world file, validates it and writes it to ancha/worlds/<id>.yaml. Runs read only that file, so you can edit it freely.

​
Model key

world gen calls a model through OpenRouter and spends credit. It needs OPENROUTER_API_KEY in the shell that runs it. Without the key it stops before writing anything:
Output
A key the provider rejects, a key that is out of credit, or an overloaded provider also stop the command, each with a hint that says so.

​
Example

Output
The id, the people and the numbers depend on the description and the model’s answers. The command prints one progress line per step, and a line for each answer it rejected and asked for again.

​
What it writes

The seed holds what the description implies: Slack users and channels with threaded messages, GitHub repositories with files, commits, pull requests and labeled issues, PagerDuty users, policies and services, and HubSpot companies, contacts and deals. The people carry a goal, a style, facts they share when asked and decisions they make by rule. See Test file for every field.

​
Sizes

​
Tools

--tools accepts slack, github, pagerduty and hubspot, and defaults to the tools the description implies. Any other tool exits 2. To use one in the world, add its seed to the generated file by hand; ancha sandbox configuration --tools <tool> --json prints starter data to copy from.

​
Using the world

A world file holds everything a scene holds except the task and the checks. To run an agent against it, copy it to scenes/<name>/scene.yaml, remove version and generated, rename tools to twins and rules to world_rules, add task and checks, and validate it with ancha scene validate. Then run it with ancha run or start it with ancha world up --scene.

​
Repeating safely

With --idempotency-key <key>, running the same command again returns the first result instead of calling the model, as long as its files still exist. The text output then starts with reused and the JSON has reused: true. The same key with different arguments exits 2:
Output
world gen never overwrites a file unless you pass --force:
Output
--from <file> starts from an existing world: its company, people and tools stay unless the description changes them.

​
JSON output

​
Exit codes

0 when the files are written or reused. 2 for a missing model key, an unknown tool, a --size other than s, m or l, --variants outside 0 to 10, an --id with characters other than lowercase letters, digits and hyphens, an existing file without --force, or an idempotency key reused with different arguments.