gateway CLI from the
@withgateway/sdk npm package; the platform hosts the world. The package bundles the schema
runtime and runs it with any python3 >= 3.12 it finds (no pip); without one, the platform
runs the same code for you.
For an agent doing the work, gateway worlds skill worlds-getting-started prints the same
steps in agent form, and --install . puts it in your repository’s .claude/skills/.
Before you begin
Install the SDK with the CLI and sign in with a project’s keys.GATEWAY_HOST, GATEWAY_PUBLIC_KEY and GATEWAY_SECRET_KEY in the environment. The
world lands in the project the keys belong to.
The one-command path
When the SDK ships a template for your vendor,gateway worlds create builds the world on the platform in one call. No directory needed.
READY and already serving the vendor’s routes. Open a session and the world answers — no pull, edit and push step first. --from workspace:<slug> does the same from a connector your organization published, and --from ./some-dir from a directory.
Use the longer path below to author the contract yourself.
Choose where to start
A world is read and write. A lookup-only mock tests nothing about the decisions your
agent makes when it creates, updates and polls. Plan the write routes from the start.
What a world is made of
A world is agateway-world/1 tree: schema/world.json, gateway-env.toml, optional
tools/handlers.py, and an optional connector.toml with api/handlers.py. Tools and HTTP
routes are two surfaces of one world, served by one session.
1
Start the world
schema/world.json (entities, fields, keys,
relationships), optional connector.toml (the vendor connection and the routes the world
answers), optional handlers in tools/handlers.py and api/handlers.py, and
scenarios/<name>/ for named starting states.The custom contract starts with one example entity, records. Declare your own with
gateway worlds schema entity add, then remove the example with
gateway worlds schema entity remove ./vendor-world records; init prints both as next steps.2
Check it
check validates the compiled bundle. With a vendor OpenAPI document,
gateway worlds connector conform ./vendor-world --openapi vendor.yaml calls every
declared route and reports each mismatch.3
Put data in
rows.json is {"<entity>": [row, ...]}. Rows that break the contract are refused with the
field named, and nothing is written. To load captures from the real vendor instead, run
gateway worlds connector capture then ingest. Details on both: Put data in a
world.4
Publish a version
gateway bench push and gateway worlds create <slug> --from ./vendor-world both store the
tree as it is: the World Host serves its routes from connector.toml and its tools from the
same session.With [actions] on_push = ["tests"] in gateway-env.toml, the platform runs the world’s own
test suite on every push. gateway bench tests <slug> lists those runs, newest first, and
--run <id> prints one report. See Test a world.Publish the template to let others in your organization start worlds from the same contract:5
Open a session
--surface api, the hosted api.url that answers the vendor’s routes plus the token to
send as Authorization: Bearer <token> on every request. Point your agent’s client at it.On a schema world whose tree carries connector.toml, the host session serves tools and api
together whether or not --surface api asked for it. On a tree with no connector.toml the
ask is refused with a 400 saying the world declares no HTTP routes.To try rows without making a version, seed the session only:
gateway worlds session seed <sessionId> rows.json.6
Run and grade
One session grades one attempt. To run a whole world, point the CLI at an agent module whose
default export is Attach a set of scenarios from a file:The
async (session, task) => void.environment namespace is the historical name for a world. The commands operate on the
world you name.7
Test the world itself
A world’s own tests check that the world answers the way the vendor does. They are separate
from the runs you grade an agent with, and they live in
<world>/tests/: *.json HTTP cases
and test_*.py files that receive WORLD_URL and WORLD_API_KEY.gateway worlds test exits 1 when any case fails. Test a world has the case
format and the push wiring.8
Iterate
Where it shows up
- Connectors in the project sidebar: shipped and workspace connectors, each with Create world and Clone, and New connector to start one on the platform: name it, then choose to keep it as a connector, create a world from it, or both. The form also shows the CLI commands that do the same.
- A connector’s page: Overview (schema and verdict), API (the routes the world serves), Worlds (the worlds built from it).
- A world’s page under Worlds: Overview, Scenarios, Schema, Data, Tests, Results, Evals and History tabs. History lists every version with its change reason; Schema shows the entities and the pin back to the connector; Tests holds the runs of the world’s own suite, including the ones the platform ran on push.
Working over MCP instead of a shell
Every step above has a tool on the platform’s MCP server:list_connectors,
get_connector, validate_connector_template, publish_connector,
init_world_from_connector, env_write_file and env_commit to land files,
import_world_data, seed_world_session, export_world_session, run_evaluation,
create_task_set, link_task_set, env_diff and env_propose. Call guide with topic
connectors or world-data for the walkthrough. See MCP Server.
Where to go next
Running the world you just built.- Spin worlds up and down for the session lifecycle: open, pin, seed, close.
- Run many sessions at once for a whole scenario set in parallel.
- Test a world for the suite a world ships for itself.
- Benchmarks on worlds to turn the world’s tasks into k graded rollouts per model.
- Run API worlds in CI for gating a pull request on the score.
- Simulations for your users for handing a world to the people who use your product.
- Put data in a world for the rows file, modes and live seeding.
- Keep real data out for the
[redact]policy before real records go in. - Mock any vendor API for
connector.toml, capture, handlers and conformance. - Build a Slack world for a populated example from the Connectors page.
- What makes a world good for the bar to aim at.
- Author worlds from chat to let the Assistant do the authoring.
- The sample repository for a working world to read and copy.
- Worlds client to drive sessions from Python.
- Evaluation & Replay for how a world’s runs are scored.
- Scenarios & task sets for curating the questions a world is asked.