Connect a coding agent¶

By the end of this guide your coding agent will send its requests to your gateway, using a virtual key issued to you alone, and you will be able to see what it spends.

The console walkthrough covers the same operations in the web console. The overview describes what changes once the agent runs against your gateway.

Each agent's own documentation is the schema

This page gives you the three values to set and points at each tool's documentation for where to put them. Agent configuration files and variable names belong to those tools and change with their versions, so reproducing a schema here would only go stale.

Prerequisites¶

A running gateway - see Deploy an LLM gateway
Admin access to it, or a colleague who can issue you a key
A coding agent installed locally

Collect the three values¶

Everything below needs the same three things. Gather them first.

Value	Suggested variable	How to find it
Base URL	`GRN_BASE_URL`	the gateway's route, with `/v1` appended
Virtual key	`GRN_API_KEY`	issued in step 2
Model name	-	the names registered behind the gateway

Naming them for GRN.CLOUD rather than reusing OPENAI_* is deliberate - see step 3.

Steps¶

1. Confirm the gateway is reachable from your machine¶

A gateway deployed for in-cluster callers has no external address. Check for a route before configuring anything:

oc get route -n <gateway-project>

If there is no route, either publish one - see Load balancers - or forward the port locally while you test:

oc port-forward -n <gateway-project> svc/<gateway-service> 8080:8080

Your base URL is then http://127.0.0.1:8080/v1.

A port-forward is not a deployment

It lasts as long as the command runs, on one machine, with no TLS. Use it to prove the connection works, then publish a route for anything ongoing.

2. Issue a virtual key for the agent¶

Give the agent its own key rather than reusing one. Attach a budget, a rate limit and a model scope - see Add a user to the gateway.

Name it so you can tell later what it was for: the tool, and whose machine it is on.

3. Keep your gateway key in its own variable¶

Most of these tools read the conventional OpenAI variables - OPENAI_API_KEY and OPENAI_BASE_URL - because they use the OpenAI SDK underneath. It is tempting to export your gateway key into OPENAI_API_KEY and be done. Do not.

Those two variables are a matched pair: the key is only valid at the host the base URL points to. Export one without the other and you have pointed a credential at the wrong server.

flowchart TB
    subgraph BAD["OPENAI_API_KEY set globally to a gateway key"]
        direction TB
        T1["a tool you pointed at the gateway"] -->|gateway key| G1["your gateway - works"]
        T2["any other tool on your machine"] -->|"gateway key"| O1["api.openai.com<br/>your gateway key, sent to a vendor"]
    end
    subgraph GOOD["each pair kept together"]
        direction TB
        T3["agent, configured explicitly"] -->|GRN_API_KEY| G2["your gateway"]
        T4["a tool using a real vendor key"] -->|OPENAI_API_KEY| O2["api.openai.com"]
    end

So give the gateway values names of their own, and never put them in the vendor variables globally:

export GRN_BASE_URL="<base-url>"        # (1)!
export GRN_API_KEY="<your-virtual-key>" # (2)!

Your gateway's endpoint, ending in /v1. From step 1.
The virtual key issued to you in step 2. This is a GRN.CLOUD credential and is only valid at the URL above - it is not a provider key and will not work anywhere else.

Then map them in where a tool needs the OpenAI names, scoped to that one command rather than exported into your shell:

OPENAI_BASE_URL="$GRN_BASE_URL" OPENAI_API_KEY="$GRN_API_KEY" <your-agent-command>

Or set them inside the tool's own configuration, which is better still because it cannot leak into anything else.

Two mistakes here produce no error message

Export a gateway key into OPENAI_API_KEY and every other tool on your machine that talks to OpenAI now sends your GRN.CLOUD key to a third party. It will be rejected, and it will also be in someone else's logs.

Export a gateway base URL into OPENAI_BASE_URL while a real vendor key is already in OPENAI_API_KEY, and you have just sent your paid vendor key to the gateway.

Neither produces an obvious error. Rotate any key you think has taken either trip.

Where a tool uses its own variable names, it is still the same three values:

Tool	What to set	Where it is documented
OpenCode	a custom OpenAI-compatible provider, with base URL, key and model	OpenCode, and the OpenCode configuration reference
Claude Code	the base URL and auth token variables it reads at startup	`claude config` and the Claude Code settings docs
Codex CLI	a model provider entry in its config file	the Codex CLI configuration reference
Editor assistants	usually a settings pane taking base URL, key and model	the extension's own settings

Read the key from a secret store, not a file in the repository

A key pasted into a configuration file inside a working tree is a key that gets committed. Keep it in your password manager and load it into GRN_API_KEY at the start of a session.

4. Find the model names¶

Ask the gateway what it serves. The endpoint is the standard OpenAI one:

curl -sS "$GRN_BASE_URL/models" \
  -H "Authorization: Bearer $GRN_API_KEY"

The id of each entry is the name to configure. These are the gateway's names, not the provider's - see Add a model provider.

5. Point the agent at a model that suits it¶

Configure the agent's main model to one with a long context and reliable tool calling, and keep a smaller local model for completion if the tool distinguishes them. See Not every model suits an agent.

Verify¶

Work outwards, so a failure tells you where it is. Each step rules out the one before it.

1. The gateway answers and the key is accepted:

curl -sS "$GRN_BASE_URL/models" \
  -H "Authorization: Bearer $GRN_API_KEY"

A connection error means the gateway is unreachable; an authentication error means the key is wrong or inactive.

2. The model name resolves and completes:

curl -sS "$GRN_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $GRN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<model-name>","messages":[{"role":"user","content":"Say hello"}]}'

An error naming the model means it is not registered, or your key's model scope excludes it.

3. Tool calling works - the part a coding agent depends on and a plain chat test does not exercise. Send a request with a tools array and confirm the response contains a tool call rather than prose describing one.

4. The agent itself works. Only now start the agent. If steps 1 to 3 passed and the agent fails, the problem is its configuration, not the gateway.

5. The request was attributed. Check the gateway's logs and confirm the calls appear against your key with token counts. This is what you set the whole thing up for.

Clean up¶

Revoke the key when the agent no longer needs it. Deactivating keeps the spend history:

unset GRN_BASE_URL GRN_API_KEY

Then deactivate or delete the virtual key - see Add a user to the gateway. Remove any port-forward by stopping the command.

Next¶

OpenCode → - the same three values in OpenCode's own configuration, its OAuth path, and where it records token counts.

Deploy an MCP server → - give the agent tools as well as a model.