Understand gx.yml and templates

A Glxymesh project has two layers of configuration: gx.yml describes the whole server and each tool.yml describes one callable tool. An HTTP tool also has a request template that fills in values when the tool is called.

• Directoryhelpdesk/

  • gx.yml project identity and defaults
  • Directorytools/

    • Directorylist-open-issues/

      • tool.yml interface and HTTP request

Read YAML first

server:                             # A group of settings
  title: Acme Helpdesk              # A string inside server
network:
  allow:                            # A list inside network
    - api.github.com                # One list item
inputs:
  limit: {type: integer, default: 3} # Short form of a nested group

Use spaces for indentation, not tabs. Siblings line up; indented values belong to the key above them. # begins a comment outside a quoted string. true and false are booleans; 3 is a number; "{limit}" is a string containing a placeholder. {type: integer, default: 3} is a compact mapping, while [api.github.com] is a compact list. You can write either in expanded form.

The project file, explained

gx.yml

spec: glxymesh/project@v1
org: acme
project: helpdesk
lang: node

server:
  title: Acme Helpdesk
  description: Read GitHub issues to help support agents investigate reports.
  website: https://acme.com

defaults:
  timeout: 10s
  memory: 256MB
  output: json

Setting	Meaning in this example
spec	The version of the project configuration format. Keep glxymesh/project@v1.
org	The organization slug that owns the deployment. Replace acme with yours.
project	The project slug. Here the endpoint is https://acme.mcp.glxymesh.com/helpdesk.
lang	The language for all function tools: node for TypeScript, go or python. HTTP tools do not need code.
server.title	A readable title a client can display. It is not the project slug.
server.description	The purpose of the whole server, which helps a model understand it.
server.website	An optional HTTPS website clients can show. It is not the MCP endpoint.
defaults.timeout	The time a call may take unless the tool overrides it. 10s means ten seconds.
defaults.memory	The memory requested for function tools unless overridden. 256MB means 256 megabytes.
defaults.output	The result format: json, text, or toon. It does not set the input format.

gxmesh init --lang node --org acme --project helpdesk generates this structure. Edit the generated values to match your project. gx.yml is ordinary configuration: it does not substitute shell variables such as $ORG or ${PROJECT}. Use real slugs in the file.

A complete HTTP tool

From an initialized project, create the directory and scaffold:

gxmesh new list-open-issues --kind http

Replace its generated tool.yml with the following. It calls a public GitHub API and needs no token for public repositories, subject to GitHub’s unauthenticated rate limits.

tools/list-open-issues/tool.yml

spec: glxymesh/tool@v1
name: list-open-issues
kind: http
description: List open issues in a GitHub repository. Supply its owner and repo name.
read_only: true

inputs:
  owner:
    type: string
    description: GitHub user or organization, for example golang
  repo:
    type: string
    description: Repository name, for example go
  limit:
    type: integer
    default: 3
    min: 1
    max: 10

network:
  allow: [api.github.com]

request:
  method: GET
  url: https://api.github.com/repos/{owner}/{repo}/issues
  query:
    state: open
    per_page: "{limit}"
  headers:
    Accept: application/vnd.github+json

response:
  pick: "[].{number: number, title: title}"

output:
  format: json

tests:
  - name: public repository responds
    input: {owner: golang, repo: go, limit: 2}
    expect: {contains: number}

Identity and inputs

spec selects the tool schema. name matches the tool directory and the CLI name you call. kind: http means Glxymesh performs one HTTP request; kind: function runs your code instead. description tells the model when to use this tool. read_only is a hint for clients that the tool reads information without changing it; it does not enforce permissions on an external API.

inputs describes the arguments the model can supply. owner and repo are required strings. limit is an integer, defaults to 3 when omitted, and must be between 1 and 10. The platform checks these arguments before making the request.

Requests and placeholders

With this call:

gxmesh call list-open-issues '{"owner":"golang","repo":"go","limit":2}'

The request template becomes:

GET https://api.github.com/repos/golang/go/issues?state=open&per_page=2
Accept: application/vnd.github+json

Template	Where its value comes from
{owner}	The owner input; fills one URL path segment
{repo}	The repo input; fills one URL path segment
"{limit}"	The numeric limit input, placed in the query string
state: open	A constant you chose, not an input
network.allow	The hosts this tool is allowed to contact; a hostname without https:// or a path

Quote placeholders used as whole YAML values, for example per_page: "{limit}". The platform substitutes input names in the request path, query, headers and body. The host stays fixed. These are Glxymesh request templates, not JavaScript expressions or shell commands.

Response, output and tests

response.pick is a JMESPath expression: [] selects each item from the API’s array, and {number: number, title: title} keeps two fields per item. These braces belong to JMESPath; they are not input placeholders. output.format: json controls how that result is presented to the model. GitHub’s issues endpoint can also include pull requests; this template keeps the endpoint’s behavior.

tests calls the real tool with the supplied input. Here expect.contains checks that the formatted answer contains number. It is a live API test, so API outages and rate limits can affect it.

gxmesh test list-open-issues
gxmesh push

Run the test first. Then push validates, deploys and runs the platform checks. Adding api.github.com to a project’s allowed hosts requires approval before it goes live.

How defaults and overrides work

A tool can override project defaults:

Inside a tool.yml

limits:
  timeout: 30s
  memory: 512MB
output:
  format: text

This tool uses a 30-second timeout instead of the project’s 10 seconds and requests 512 MB for function execution. Other tools keep their own settings or the project defaults. Function tools share the project’s runtime: the highest memory request sets the deployed runtime’s memory and can affect the compute cost of every function call. See the gx.yml reference.

Where secrets belong

Store production values in the console’s project secrets and local values in .env.local. Declare how a tool can use a secret in its tool.yml:

Optional tool.yml binding for authenticated GitHub requests

secrets:
  GITHUB_TOKEN:
    hosts: [api.github.com]
    header: "Authorization: Bearer {value}"

GITHUB_TOKEN names a saved secret. {value} is a special placeholder for its value, injected by the gateway only on the listed hosts. It is not a model-supplied input. This binding does not create the secret; save its value separately before running the tool.

Three different kinds of braces

{"owner":"golang"} is JSON supplied to a command. "{owner}" is a request input placeholder. "Authorization: Bearer {value}" uses a secret binding placeholder. Each belongs in its own context.

Common configuration mistakes

Mistake	Fix
Putting every tool inside gx.yml	Create a separate tools/<name>/tool.yml for each tool.
Leaving api.example.com in a scaffold	Replace the request URL and network allowlist with the actual API host.
Calling an undeclared host	Add the host to network.allow, then test and review the push approval.
Renaming an input only in the request	Keep its declaration, every placeholder and all test inputs in sync.
Editing generated input files	Edit inputs in tool.yml, then run gxmesh gen.
Saving a token in committed YAML	Save its value in project secrets or .env.local and declare a binding.

Continue with the gx.yml field reference, tool.yml field reference, or CLI walkthrough to run the full workflow.