Skip to main content
A world is a sealed copy of the systems your agent works against. The platform hosts it, serves the vendor’s routes, and pins every version, so two runs differ by exactly the thing you changed. The eight steps below end with a world in your project, a live session your agent called, and a graded number you can compare against tomorrow’s agent.

​
What you need before the first command

Both keys are one credential. A key pair is a public key (pk-lf-…) and a secret key (sk-lf-…), and every request sends both: the public key is the username half of HTTP Basic auth and the secret key is the password half — see REST API overview.
The secret key is displayed once, at creation time. Copy both keys out of the dialog before closing it; a lost secret key is replaced, never recovered.

​
The path, end to end

1

Install the command-line tool

The @withgateway/sdk npm package ships the gateway command. Install it globally so it is on your path.
A successful install prints the command groups — auth, worlds, bench, environment and the rest. Installation covers the Python SDK.
2

Sign in to your project

gateway auth login stores the host and the key pair in a credentials file that every later command reads.
gateway auth status prints the host in effect and whether a key is configured. In continuous integration, set GATEWAY_HOST, GATEWAY_PUBLIC_KEY and GATEWAY_SECRET_KEY instead; the environment wins over the stored file.
3

Create a world from a shipped connector

A connector template is a vendor’s data model and routes, already written. gateway worlds create cuts a world from one and publishes its first version in a single call.
The command prints one line: the slug, the first version’s content hash, and the world’s page in the app (https://<host>/project/<projectId>/world?env=<containerId>). The first version is READY. worlds schema templates lists every template the package installs, so swap slack for the vendor you care about.The world is stored as its schema tree — the contract, the handlers, and the connector file that declares the vendor’s routes. One session serves both of its surfaces: the world’s tools, and its HTTP routes.
Driving a coding agent instead of a terminal? The same call is the MCP tool create_world, which takes slug, from, an optional overlay and seed data. See MCP Server.
4

Open a session and read where it answers

A session is one live, pinned copy of the world. Ask for the api surface and the platform serves the vendor’s HTTP routes at a URL of their own.
The descriptor comes back as JSON:
-t names the task the session opens on, and a world built from a template ships one called default. -s api asks for the HTTP surface explicitly; a world whose connector declares routes serves them from the same session either way, and a world that declares none refuses the ask with a 400 naming the missing connector.toml.
5

Point your agent at the session

The api.url is a base URL and the api.token is a bearer token. Give your agent those two values where it would otherwise take the vendor’s, and change nothing else about it.
Send the token in the header, never in the URL. Which paths exist depends on the world’s contract: the world’s API tab lists every route, and gateway worlds session status <sessionId> prints the session’s tools and surfaces.To confirm the world is live without knowing a route, dump its rows:
6

Grade the end state

The task carries a grader. grade runs it against the world as it stands now and prints a reward.
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 the verdict.
7

Close the session

A session holds a running container, so hand it back when you are done.
Sessions close themselves after thirty idle minutes. gateway worlds session pin <sessionId> exempts one from the idle reaper while you work on it.
8

Read the result in the dashboard

Open the project and select Worlds, then your world. The page carries Overview, Scenarios, Schema, Data, Tests, Results, Evals and History tabs.Overview lists every live session with its engine, state, task, API URL and age, plus Pin and Stop. History lists every version with the change reason recorded on it, which is what makes an old score still readable months later.

​
Run every scenario with one command

Point the CLI at an agent module and it opens a session per scenario, runs your agent, and grades each end state.
The module default-exports async (session, task) => void. The summary JSON on stdout carries one entry per scenario with its reward, plus the mean across all of them.

​
The two branches from here

​
Where to go next