Quickstart

Create a world, open a live session against it, call it over HTTP, and read a score. Everything here runs with the gateway command-line tool; the platform does the hosting. This page assumes you finished Installation: @withgateway/sdk is installed and gateway auth status prints your host.

Prefer to hand the work to a coding agent? gateway worlds skill worlds-getting-started prints the same path in agent form, and --install . writes it into your repository’s .claude/skills/.

Create a world

A world is a sealed copy of a system your agent works against. Start one from a connector template the SDK ships, or from a contract you write yourself.

From a connector template
From your own contract

gateway worlds create builds the world on the platform in one call. Pass a shipped template slug to --from; gateway worlds schema templates lists what is installed.

gateway worlds create acme-slack --from slack -m "first world"

The template is pinned on the world, the platform compiles it, and the first version is READY and serving. There is no separate push step.

Start a directory from the blank contract, compile it, and push it as the world’s first version.

gateway worlds schema init ./acme-world --connector custom --name acme-world
gateway worlds schema compile ./acme-world
gateway worlds schema check ./acme-world
gateway bench push ./acme-world -m "first cut"

The directory holds the contract in schema/world.json (entities, fields, keys, relationships), an optional connector.toml naming the vendor connection and the routes the world answers, and scenarios/<name>/ for named starting states. Getting started with worlds walks through each file.

gateway worlds list now shows the world with its slug and latest version.

Open a session

A session is one live, pinned copy of the world. Ask for the api surface and the platform serves the world’s routes at a URL your agent can call.

gateway worlds session open acme-slack -t default -s api

-t names the task the session runs, and every world built from a template ships a task called default. -s api asks for the HTTP surface on top of the tool surface; repeat it or comma-separate it for ui and browser. The command prints the session descriptor:

{
  "sessionId": "ws_01J...",
  "ready": true,
  "surfaces": ["tools", "api"],
  "api": { "url": "https://...", "token": "..." }
}

Call the world over HTTP

The api.token in the descriptor authorizes every request. Send it as a bearer token in the header, never in the URL.

export API_URL="https://..."     # api.url from the descriptor
export API_TOKEN="..."           # api.token from the descriptor

curl -s "$API_URL/<operation-path>" \
  -H "Authorization: Bearer $API_TOKEN"

Which paths exist depends on the world’s contract. A world’s API tab in the dashboard lists every route it serves, and gateway worlds session status <sessionId> prints the session’s tools and surfaces. For a world you have a directory for, gateway worlds schema describe ./acme-world prints its entities, tools, and the vendor connection it answers to. To confirm the world is live without knowing a route, dump its current rows:

gateway worlds session state <sessionId>

Point your agent’s vendor client at $API_URL with that bearer token and it works against the world instead of the real system. Nothing it writes leaves the session.

Grade the run

The session’s task carries a grader. grade runs it against the world’s state as it stands now and prints the reward.

gateway worlds session grade <sessionId>

{ "reward": 1.0, "rewards": { "channel_created": 1.0 }, "raw": { } }

reward is the headline number, rewards breaks it down per check, and raw holds whatever the grader returned. Assertion and Python graders answer in seconds; a rubric judge is scored by the platform’s worker, and the command waits for that verdict.

Want a different question asked? gateway worlds session open --task-file spec.json supplies a task inline: {instruction, seed?, grader?, metadata?}. gateway worlds task create keeps the same spec as a project resource so sessions can open on it by id.

Close the session

A session holds a running container, so close it when you are done.

gateway worlds session close <sessionId>

Sessions close themselves after 30 minutes without a call. To keep one up while you work, gateway worlds session pin <sessionId> exempts it from the idle reaper until you close it.

What to do next

Build a world properly, with your own contract, real data, and versions, in Getting started with worlds.
Run every task in a world at once with gateway worlds run, and gate a pull request on the score with gateway worlds ci. See The gateway CLI.
Capture the sessions a world is seeded from in Tracing.
Score production traffic and replay real sessions in Evaluation & Replay.
Learn the six words the product is built from in the Glossary.

Start here

Get Started

Use cases

Worlds

Evaluation & Replay

Tracing

Hooks

Create a world

Open a session

Call the world over HTTP

Grade the run

Close the session

What to do next

​Create a world

​Open a session

​Call the world over HTTP

​Grade the run

​Close the session

​What to do next

Create a world

Open a session

Call the world over HTTP

Grade the run

Close the session

What to do next