N·05Integration guides

Cursor

An AI-native code editor with built-in support for OpenAI-compatible services; enter the address and key to swap the default model for XylemNode's.

  1. 01

    Open model settings

    Open Cursor settings and go to the Models tab. To avoid clashing with the built-in models, first turn off the ones enabled by default.

  2. 02

    Add a custom model

    In the model list, click "Add model" and enter the model name you want by hand (e.g. gpt-6.1-sol); it must match an available model in the console.

  3. 03

    Override the Base URL and add the key

    Under API Keys, find OpenAI API Key, paste your key and switch on the toggle next to it, then tick "Override OpenAI Base URL" and enter the address. It uses the OpenAI-compatible format, so the address needs /v1; click Verify once, then save when it passes.

    yaml
    Base URL: https://api.xylemnode.com/v1
    API Key:  sk-your-key
    Model:    gpt-6.1-sol
  4. 04

    Pick a model and test

    After saving, start a new chat, select the gpt-6.1-sol you just added from the model dropdown, and send a message to confirm.

Alternative: cursor-byok (third-party)

cursor-byok is a community-made third-party tool that runs a local service and forwards Cursor's requests to the endpoint you configure. Follow its own docs for exact steps — the outline below is approximate. When the native method above works, prefer it.

  1. 01

    Download and launch

    Download the package for your OS from cursor-byok's GitHub Releases, unzip and launch it.

  2. 02

    Enter the upstream config

    In its config, point the upstream at XylemNode: use the OpenAI-compatible endpoint (with /v1), then enter the key and model name.

    terminal
    Base URL: https://api.xylemnode.com/v1
    API Key:  sk-your-key
    Model ID: gpt-6.1-sol
  3. 03

    Connect to Cursor and restart

    Follow the tool's instructions to connect it to Cursor, then fully quit and reopen Cursor so the config takes effect.

  4. 04

    Pick a model and test

    In Cursor's model list, select the model connected via cursor-byok and send a message to confirm.

Common questions

The endpoint and key are set in Cursor, but the model is ignored or the agent reports BAD_MODEL_NAME

Three things to check. First, pasting the key and switching on the toggle next to OpenAI API Key are two separate actions, and the base URL override only applies while the key is active — pasting without enabling is the usual cause. Second, once the override is on, Cursor's built-in models are routed through it too, so switch the override off to go back to them. Third, a custom model works in the main agent pane but is silently ignored by subagents; that is a current Cursor limitation, not a mistake in your config.

Cursor says a custom model already exists, or refuses to add it

The name collides with the internal ID of one of Cursor's built-in models, so it is treated as a duplicate and reported as already available. Enter the full identifier from the console (gpt-6.1-sol, for instance) rather than a short name that might match a built-in ID.