Edgegap

List the applications in the Edgegap organization. Start here before creating or deploying anything, so you reuse an existing application instead of making a duplicate. An "application" groups versions of one game server.

{
  "type": "object",
  "properties": {
    "limit": {
      "description": "Results per page. Default 50.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Create a new application to hold game server versions. Only call this after edgegap_list_apps confirms no suitable application exists. Creating an application does not deploy anything — follow with edgegap_create_app_version.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 3,
      "maxLength": 64,
      "description": "Application name, 3-64 chars. Usually the game or project name."
    },
    "is_active": {
      "description": "Whether deployments are allowed. Default true.",
      "type": "boolean"
    }
  },
  "required": [
    "name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the versions under an application, with their container image and resource settings. Use this to find the version name to deploy, or to copy settings from a working version when creating a new one.

{
  "type": "object",
  "properties": {
    "application": {
      "type": "string",
      "description": "Application name, as returned by edgegap_list_apps."
    }
  },
  "required": [
    "application"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Register a container image as a deployable version of an application. The image must already be pushed to a registry that Edgegap can pull from. Resource units: 1024 cpu units = 1 vCPU; memory_mb must be at least 256 and at most double the cpu units. Set verify_image true on the first version so a bad image fails here rather than at deploy time. Avoid the "latest" docker tag — use a build ID so deployments are reproducible.

{
  "type": "object",
  "properties": {
    "application": {
      "type": "string",
      "description": "Existing application name."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Version identifier, typically a build ID or timestamp."
    },
    "docker_repository": {
      "type": "string",
      "description": "Registry host, e.g. \"docker.io\" or \"registry.edgegap.com\"."
    },
    "docker_image": {
      "type": "string",
      "description": "Namespaced image, e.g. \"mystudio/game-server\"."
    },
    "docker_tag": {
      "type": "string",
      "description": "Image tag. Use a build ID, not \"latest\"."
    },
    "cpu_units": {
      "type": "integer",
      "minimum": 256,
      "maximum": 9007199254740991,
      "description": "vCPU units. 1024 = 1 vCPU."
    },
    "memory_mb": {
      "type": "integer",
      "minimum": 256,
      "maximum": 9007199254740991,
      "description": "Memory in MB. At most 2x cpu_units."
    },
    "ports": {
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "port": {
            "type": "integer",
            "minimum": 1,
            "maximum": 59999,
            "description": "Port the server listens on."
          },
          "protocol": {
            "type": "string",
            "description": "UDP, TCP, WS, or HTTP. Most game servers use UDP."
          },
          "name": {
            "description": "Label, e.g. \"gameport\".",
            "type": "string"
          },
          "to_check": {
            "description": "Readiness check on this port. Default true.",
            "type": "boolean"
          }
        },
        "required": [
          "port",
          "protocol"
        ]
      },
      "description": "Ports to expose. At least one is required for players to connect."
    },
    "registry_username": {
      "description": "Registry username, for private images.",
      "type": "string"
    },
    "registry_token": {
      "description": "Registry password or token.",
      "type": "string"
    },
    "max_duration_minutes": {
      "description": "Auto-stop after this many minutes. Keeps test deployments from running up cost.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "verify_image": {
      "description": "Verify Edgegap can pull the image before accepting the version.",
      "type": "boolean"
    },
    "env": {
      "description": "Environment variables injected into the container.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        },
        "required": [
          "key",
          "value"
        ]
      }
    }
  },
  "required": [
    "application",
    "name",
    "docker_repository",
    "docker_image",
    "docker_tag",
    "cpu_units",
    "memory_mb",
    "ports"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Start one containerized instance of an application version, placed near the players you specify. Returns immediately with a request_id; the server is still starting and has no connection details yet. Follow this call with edgegap_wait_for_deployment to get the address players connect to. Always stop deployments you started for testing.

{
  "type": "object",
  "properties": {
    "application": {
      "type": "string",
      "description": "Application name."
    },
    "version": {
      "type": "string",
      "description": "Version name within the application."
    },
    "users": {
      "type": "object",
      "properties": {
        "ip_addresses": {
          "description": "Public IPv4/IPv6 addresses of the players. Edgegap places the server near them.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "geo_coordinates": {
          "description": "Latitude/longitude pairs, as an alternative to IP addresses.",
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "latitude": {
                "type": "number"
              },
              "longitude": {
                "type": "number"
              }
            },
            "required": [
              "latitude",
              "longitude"
            ]
          }
        }
      },
      "description": "Where the players are. Exactly one of these two is required."
    },
    "env": {
      "description": "Environment variables for this deployment only.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        },
        "required": [
          "key",
          "value"
        ]
      }
    },
    "tags": {
      "description": "Tags for filtering later, e.g. [\"agent-test\"]. Recommended.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "cpu_units": {
      "description": "Override the version CPU.",
      "type": "integer",
      "minimum": 256,
      "maximum": 9007199254740991
    },
    "memory_mb": {
      "description": "Override the version memory.",
      "type": "integer",
      "minimum": 256,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "application",
    "version",
    "users"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Read the current status of one deployment, including connection address and ports once it is ready. For a deployment you just created, prefer edgegap_wait_for_deployment — it polls for you instead of making you call this in a loop.

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "description": "The request_id returned by edgegap_deploy."
    }
  },
  "required": [
    "request_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Poll a deployment until it is ready, errors, or the timeout expires, then return the connection details. This is the tool to call right after edgegap_deploy. Do not build your own polling loop — this handles backoff and reports the container error detail if the server fails to start.

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "description": "The request_id returned by edgegap_deploy."
    },
    "timeout_seconds": {
      "description": "How long to wait before giving up. Default 180.",
      "type": "integer",
      "minimum": 5,
      "maximum": 600
    }
  },
  "required": [
    "request_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List active deployments, optionally filtered. Use this to find deployments left running from earlier sessions before starting new ones — orphaned servers cost money.

{
  "type": "object",
  "properties": {
    "filter": {
      "description": "Edgegap filter expression, e.g. by tag. Omit for all deployments.",
      "type": "string"
    },
    "limit": {
      "description": "Default 50.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Gracefully stop one deployment by request_id, sending SIGTERM to the container. Stop every deployment you started for testing before ending your task. This tool stops exactly one deployment; bulk stop is deliberately not exposed.

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "description": "The request_id of the deployment to stop."
    }
  },
  "required": [
    "request_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Retrieve stdout/stderr and crash output for a deployment. Call this whenever a deployment errors or a server exits unexpectedly — the crash exit code usually identifies the problem faster than redeploying does. Logs for stopped deployments are only retained if Endpoint Storage was configured on the version beforehand.

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "description": "The request_id of the deployment."
    },
    "max_characters": {
      "description": "Truncate logs to this length, keeping the tail. Default 8000.",
      "type": "integer",
      "minimum": 500,
      "maximum": 50000
    }
  },
  "required": [
    "request_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}