Skip to content

Runtime Provisioning

This guide covers runtime spec provisioning through world-runner HTTP APIs.

All mutation endpoints are admin-only.

Endpoint Summary

Legacy world and region endpoints:

  • POST /spec/region
  • GET /spec/region/{genome}
  • POST /world/spec
  • GET /world/spec

Generalized storage endpoints:

  • POST /spec/{kind}
  • GET /spec/{kind}/{id}
  • GET /spec/{kind}

Generalized instantiation endpoint:

  • POST /spec/{kind}/{id}/instantiate

Kind Behavior

Instantiable kinds (current whitelist):

  • simulation.vehicle
  • earth.animal
  • simulation.region
  • social.fate

Storage-only kinds (example):

  • simulation.quest
  • simulation.creature
  • simulation.feature

Storage-only kinds return 422 not_instantiable on /instantiate.

Typical Flow

  1. Upload specs with POST /spec/{kind}
  2. Confirm storage with GET /spec/{kind}/{id} or GET /spec/{kind}
  3. Instantiate only if the kind is whitelisted

Curl Walkthrough

Assumes a valid authenticated admin session cookie in SESSION_COOKIE.

1) Upload a quest spec (storage-only)

curl -X POST http://localhost:8080/spec/simulation.quest \ -H "Cookie: ${SESSION_COOKIE}" \ -H "Content-Type: application/x-yaml" \ --data-binary @schemas/quest/make_stew.yml

Expected response:

{ "kind": "simulation.quest", "id": "make_stew" }

2) Attempt quest instantiation (expected 422)

curl -X POST http://localhost:8080/spec/simulation.quest/make_stew/instantiate \ -H "Cookie: ${SESSION_COOKIE}"

Expected response:

{ "error": "not_instantiable", "detail": "kind 'simulation.quest' is not instantiable" }

3) Upload and instantiate a vehicle spec

curl -X POST http://localhost:8080/spec/simulation.vehicle \ -H "Cookie: ${SESSION_COOKIE}" \ -H "Content-Type: application/x-yaml" \ --data-binary @schemas/vehicle/beatle.yml

Then instantiate:

curl -X POST \ "http://localhost:8080/spec/simulation.vehicle/beatle_test_001/instantiate?region_id=coreland" \ -H "Cookie: ${SESSION_COOKIE}"

Expected response shape:

{ "kind": "simulation.vehicle", "id": "beatle_test_001", "instance": { "vehicle_id": "...", "genome": "...", "architecture": "...", "region_id": "coreland" } }

4) Upload and instantiate a fate spec

curl -X POST http://localhost:8080/spec/social.fate \ -H "Cookie: ${SESSION_COOKIE}" \ -H "Content-Type: application/x-yaml" \ --data-binary @schemas/fate/sample_fate.yml

curl -X POST http://localhost:8080/spec/social.fate/fate_001/instantiate \ -H "Cookie: ${SESSION_COOKIE}"

Expected instance status: dormant

Notes

  • Kind values support dotted and hyphenated forms in URL paths.
  • simulation.vehicle and simulation-vehicle are normalized to simulation.vehicle.
  • The raw spec store is in-memory; re-upload after runner restart.
  • Region and world dedicated endpoints remain supported and unchanged.

World Layout Engines

When instantiating a world using POST /spec/world/{id}/instantiate, the layout behavior is controlled by pluggable layout engines defined in the world spec. For a full guide on layout trait contracts, engine compatibility, and adding new engines, see LAYOUT_ENGINES.md.