Skip to main content

Set Up the Gateway for IDEs

This page prepares the Verdictan side of an IDE integration. Follow the client-specific page afterward. Editor settings are different for each editor. They change independently of the gateway.

1. Install and authenticate the CLI​

Follow Install the Gateway. Then verify the active control-plane identity:

verdictan --version
verdictan auth whoami

2. Create and validate a gateway config​

Start from the CLI scaffold:

verdictan init

Configure one or more provider targets. Do not put their credentials in YAML:

pack:
  name: ide-gateway
  version: 1.0.0
  enabled: true

providers:
  targets:
    - id: openai-primary
      provider: openai
      model: your-model-id
      base_url: https://api.openai.com
      secret_key_ref:
        env: VERDICTAN_OPENAI_API_KEY

policies:
  chain:
    - audit-logger

policy:
  audit-logger: {}
export VERDICTAN_OPENAI_API_KEY="<provider-key>"
verdictan policy lint --file policy-config.yaml
verdictan policy test --json

verdictan policy lint is silent when validation succeeds. Replace your-model-id with an ID supported by your provider. After the gateway starts, the authenticated /v1/models route shows available IDs.

3. Start the connected gateway​

You must bind a policy file to an agent. Connected mode also must have a runtime token:

export VERDICTAN_API_URL="https://api.verdictan.com"
export VERDICTAN_API_TOKEN="<gateway-runtime-token>"

verdictan gateway run \
  --agent ide-gateway \
  --listen 127.0.0.1:41002 \
  --policy-config policy-config.yaml

Verify local process health without sending a model request:

curl --fail http://127.0.0.1:41002/healthz

4. Create a different client token​

Create an API token for the developer or workload that will call the model API. Do not reuse the gateway runtime token. See Tokens and authentication.

Verify the model endpoint with that client token:

export VERDICTAN_IDE_TOKEN="<client-api-token>"

curl --fail http://127.0.0.1:41002/v1/models \
  -H "Authorization: Bearer ${VERDICTAN_IDE_TOKEN}"

Clients that support a custom OpenAI-compatible endpoint use:

http://127.0.0.1:41002/v1

The API key field in that client receives VERDICTAN_IDE_TOKEN, not the upstream provider key.

5. Optional MCP client connection​

The gateway supports MCP only on the agent's active published hostname. It does not support MCP on localhost:41002 or api.verdictan.com:

https://<published-hostname>/mcp

Copy the assigned hostname from the gateway or agent publication in the console. Use an active Access Key or Gateway Key to authenticate.

If you use the optional repository helper, it writes project files for Cursor, VS Code, and OpenCode. It does not detect installed clients. It replaces the target files and does not merge them. Run a dry run first:

export VERDICTAN_MCP_TOKEN="<mcp-client-token>"
./docker/install-mcp.sh \
  --dry-run \
  --hostname "<published-hostname>" \
  --token-env VERDICTAN_MCP_TOKEN

The dry run lists .cursor/mcp.json, .vscode/mcp.json, and opencode.json as its targets. Review existing files before you run the command without --dry-run. You can configure each client manually as an alternative.

6. Verify the IDE flow​

Open a second shell. Follow events:

verdictan events tail --since 10m --follow

Then invoke the IDE feature that you configured. If the MCP connection succeeds, this proves only tool access. It does not prove that chat or completion traffic uses the model gateway.

Next steps​