> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surfacearea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create a world, open a hosted session, call it over HTTP, and grade the result - in under ten minutes with the gateway command-line tool.

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](./installation): `@withgateway/sdk` is installed and `gateway auth status` prints your host.

<Info>
  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/`.
</Info>

## 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.

<Tabs>
  <Tab title="From a connector template">
    `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.

    ```bash theme={null}
    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.
  </Tab>

  <Tab title="From your own contract">
    Start a directory from the blank contract, compile it, and push it as the world's first version.

    ```bash theme={null}
    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](/worlds/getting-started) walks through each file.
  </Tab>
</Tabs>

`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.

```bash theme={null}
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:

```json theme={null}
{
  "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.

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
gateway worlds session grade <sessionId>
```

```json theme={null}
{ "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.

<Info>
  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.
</Info>

## Close the session

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

```bash theme={null}
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](/worlds/getting-started).
* 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](/cli).
* Capture the sessions a world is seeded from in [Tracing](/tracing).
* Score production traffic and replay real sessions in [Evaluation & Replay](/evaluation).
* Learn the six words the product is built from in the [Glossary](/glossary).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.