Skip to main content
Install the gateway command-line tool and sign it in to a Surface Area project. Signing in takes three values: a host URL, a project public key, and a project secret key.

​
Install the command-line tool

The @withgateway/sdk npm package ships the gateway command. Install it globally and it is on your path. Node 18 or newer is required.
The package bundles the world runtime, so gateway compiles and serves worlds on its own. It runs the bundled runtime with any python3 3.12 or newer it finds on the machine, and without one the platform runs the same code for you.
Worlds, sessions, data, and runs all live under gateway worlds. Run gateway worlds --help for the full list, and see The gateway CLI for the command reference.

​
Create project API keys

Your keys decide which project a command writes to. Create a pair in the dashboard.
1

Open project settings

Open your Surface Area project, go to Settings, and select the API keys tab.
2

Create a new key pair

Select Create new API keys. Add an optional note to label the pair, then confirm. Surface Area generates a public key (pk-lf-...) and a secret key (sk-lf-...).
3

Copy the secret key immediately

Surface Area shows the secret key only once, at creation time. Copy both keys from the dialog before you close it. The panel also shows a ready-to-paste .env block with the host and both keys filled in.
Dashboard basics covers signing in, finding your organization and project, and the rest of the settings surface.

​
Sign in

Pass all three values to gateway auth login. The command writes them to a credentials file that every later command reads.
gateway auth status prints the host in effect and whether a key is configured. gateway auth logout clears the stored credentials. pip install gatewaysdk installs a gateway command too. Its auth login asks for any value you leave out; the npm command needs all three flags or the three GATEWAY_* variables. Both commands write ~/.gateway/config.json (GATEWAY_CONFIG_DIR moves it). gateway auth status says (from environment) when environment variables are in effect, since they win over the file.
Never commit API keys to source control or paste them into a script. Keep them in a secrets manager or in environment variables, and read them from there.

​
Sign in with environment variables instead

Every command reads the same three environment variables, and the environment wins over the stored credentials file. Use environment variables in continuous integration, where there is no interactive login.

​
Install the Python SDK to trace an agent

Tracing captures what your agent did, and those sessions are the material a world is built from. Install gatewaysdk from PyPI to instrument an agent. The package requires Python 3.12 or newer (0.3.x ran on 3.10).
Auto-instrumentation of common LLM libraries needs one extra. Install it to trace OpenAI, Anthropic, LiteLLM, and the OpenAI Agents SDK without writing span code yourself.
Verify the connection by initializing tracing with debug="INFO". A clean run logs an init summary and exits without errors; the INFO level surfaces credential problems if any value is wrong.
The core install works with any openai release, including 3.x. Heavier features are extras; install only what you use:
Since 0.5.0, litellm and gepa are no longer in the core install (litellm pins openai below 3). Code that runs GEPA or LLMProxy on a plain pip install gatewaysdk now stops with an ImportError naming the extra, for example gatewaysdk.algorithm.gepa needs the optimize extra: pip install 'gatewaysdk[optimize]'. Run that one command to fix it.
The Quickstart does not need the Python SDK. A world created from a connector template ships with its own data and a task, so your first graded run needs nothing from production.

​
Next step

Hand the setup to your coding agent with the prompts in Start with your coding agent, or create a world by hand in the Quickstart.