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

# Installation

> Install the gateway command-line tool, sign in to a project, and install the Python SDK when you want to trace an agent.

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.

```bash theme={null}
npm install -g @withgateway/sdk
gateway --help
```

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.

<Info>
  Worlds, sessions, data, and runs all live under `gateway worlds`. Run `gateway
      worlds --help` for the full list, and see [The gateway CLI](/cli) for the
  command reference.
</Info>

## Create project API keys

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

<Steps>
  <Step title="Open project settings">
    Open your Surface Area project, go to **Settings**, and select the **API keys** tab.
  </Step>

  <Step title="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-...`).
  </Step>

  <Step title="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.
  </Step>
</Steps>

[Dashboard basics](./dashboard) 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.

```bash theme={null}
gateway auth login \
  --host https://withgateway.ai \
  --public-key pk-lf-... \
  --api-key sk-lf-...

gateway auth status
```

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

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

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

```bash theme={null}
export GATEWAY_HOST="https://withgateway.ai"
export GATEWAY_PUBLIC_KEY="pk-lf-..."
export GATEWAY_SECRET_KEY="sk-lf-..."
```

| Variable | Required | Description |
| - | - | - |
| `GATEWAY_HOST` | Yes | Surface Area server URL, for example `https://withgateway.ai`. Also settable per command with `--host`. |
| `GATEWAY_PUBLIC_KEY` | Yes | Project public key, starts with `pk-lf-`. |
| `GATEWAY_SECRET_KEY` | Yes | Project secret key, starts with `sk-lf-`. |
| `GATEWAY_OTLP_ENDPOINT` | No | Override for the trace export endpoint. Derived from `GATEWAY_HOST` when unset. |

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

```bash theme={null}
pip install gatewaysdk
```

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.

```bash theme={null}
pip install 'gatewaysdk[tracing]'
```

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.

```python theme={null}
import gatewaysdk.tracing as tracing

tracing.init(debug="INFO")
tracing.shutdown()
```

The core install works with any `openai` release, including 3.x. Heavier features are extras; install only what you use:

| Install | Adds | For |
| - | - | - |
| `gatewaysdk` | core | tracing export, worlds, sessions, the `gateway` command |
| `gatewaysdk[tracing]` | OpenInference instrumentors | auto-instrumentation of OpenAI, Anthropic, LiteLLM, the OpenAI Agents SDK |
| `gatewaysdk[optimize]` | `gepa`, `litellm` | the GEPA prompt optimizer |
| `gatewaysdk[proxy]` | `litellm[proxy]` | `LLMProxy` |
| `gatewaysdk[openai-agents]` | `openai-agents` | `AgentsComputer`, native computer use through the OpenAI Agents SDK |
| `gatewaysdk[trainer]` | `litellm[proxy]` | training orchestration |
| `gatewaysdk[gpu-monitoring]`, `[apo]`, `[mongo]` | | GPU heartbeat statistics, automatic prompt optimization, the MongoDB store |

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

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](./agent-prompts), or create a world by hand in the [Quickstart](./quickstart).


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