Gateways
A Gateway is where agents connect and where your policy is enforced. This page explains how to choose between a Gateway hosted by Gatelion and one in your own network, how to add one, and how to read, stop and retire it on the Gateways page.
Each environment has its own Gateways. Make sure the right environment is selected in the console before you add one.
Adding a Gateway is the first step of the console's Get started checklist. The step ticks itself off once the Gateway has connected to Gatelion.
Hosted by Gatelion or in your network
| Hosted by Gatelion | In your network | |
|---|---|---|
| Install | Nothing to install. Gatelion runs it. | You install it as a service on a Windows or Linux machine. See Install a Gateway. |
| Systems it can reach | Systems on the public internet only. | Systems in your network, in the private address ranges you allow, and systems on the internet. |
| Your systems' secrets | Typed into the console and sealed in your browser. Gatelion's servers store only the encrypted value. | Stay on the Gateway's machine, in its settings file. The console only stores their names. |
| Agent address | Shown on the Gateways page. | http://<that machine>:5200/mcp, or your own HTTPS address. |
| Your customers' agents | Can be set up for them. | Your own agents only. |
Choose hosted when the systems your agents use are reachable on the internet (a SaaS API, or your own public API) and you don't want to run a server.
Choose your network when any system is internal: an ERP on 10.x addresses, an API behind your firewall. A hosted Gateway can't reach private networks, and connections it calls must use public addresses.
You can have both in one environment. Each connection is called either by your own Gateways or by one hosted Gateway (see Connect a system).
Add a Gateway
- Open Gateways and click Add Gateway.
- Choose Where it runs: In your network or Hosted by Gatelion.
- For a hosted Gateway, choose Which agents connect, where Gatelion offers access for outside agents. Your own agents, with agent tokens is for agents your organization runs. Your customers' agents, after the customer signs in is for outside agents; see Your customers' agents.
- Give it a Name, for example
erp-dc-1, and click Add Gateway.
What happens next depends on where it runs:
- In your network: the page shows a registration code (
gwreg_…) and an Install this Gateway panel with the download and the commands for each system. The code is shown once, works once, and expires after 15 minutes. Follow Install a Gateway. - Hosted by Gatelion: there's no code. The row shows Being set up by Gatelion… until it's ready, and its MCP address appears in the list.
Adding a Gateway is refused with quota_exceeded when your organization has reached its limit of Gateways or hosted Gateways. If Gatelion's hosted Gateways are full, adding a hosted one is refused with hosted_full: try again later, or run one in your network.
Registration codes
A Gateway in your network proves who it is with a registration code the first time it starts. After that it uses its own private key, which never leaves its machine.
If the code expires before the Gateway registers, the row shows Not registered yet: get a new code. Click it to get a new code, valid for another 15 minutes. Then put it in the installer command, or in the Gateway's settings file if it's already installed (see Troubleshooting).
Read the list
| Column | What it tells you |
|---|---|
| Gateway | Its name, where it runs (In your network or Hosted by Gatelion), and its software version. A hosted Gateway for outside agents also says for your customers' agents. Hosted Gateways show their MCP address and a copy button. |
| Last sync | When the Gateway last fetched its configuration. A healthy Gateway syncs about every 15 seconds. never means it hasn't registered yet. |
| Configuration | The configuration version it runs, like v12 · current. update to v13 pending means you've made changes it hasn't fetched yet. It normally catches up on its next sync. none yet means it hasn't fetched one. |
| If it loses contact | The worst case if the Gateway can't reach Gatelion, for example "Writes stop after 15 minutes, reads after 1 hour". |
| Running | The switch that stops or starts the Gateway. A stopped Gateway also shows Retire under it. |
If it loses contact
A Gateway that can't reach the Control Plane keeps working with the configuration it has, but only for a limited time. Once its configuration is older than the write window it refuses writes, and once it's older than the read window it refuses reads too. The column shows these windows for the environment, so you know the longest a change could take to reach a disconnected Gateway.
An admin sets the windows for each environment on Settings, under If a Gateway loses contact with Gatelion: Reads stop after and Changes stop after. Gateways apply new times at their next sync. See Settings.
Calls that need approval never run without live contact with Gatelion, whatever the windows are. See Gateways and sync.
Stop a Gateway
Turn off the Running switch. The Gateway stops on its next sync, normally within about 15 seconds. From then on it refuses every tool call, and agents connected to it see only the status tool.
Turn the switch on again to restart it. It resumes on its next sync.
Stopping a Gateway doesn't cancel requests waiting for approval. They can still be decided, but an approved request can't run through the Gateway while it's stopped.
Retire a Gateway
When you no longer need a Gateway, retire it. A retired Gateway is refused for good: it can't come back.
- Stop it first. Turn off its Running switch. Retiring a Gateway that's still running is refused (
gateway_running). - Click Retire under the switch. The confirmation lists what changes; type the Gateway's name and click Retire Gateway.
- For a Gateway in your network, uninstall it from its machine. See Uninstall.
When a Gateway is retired:
- It can't sync or serve agents again. Its next sync is refused.
- It no longer counts toward your organization's limits. See Usage and limits.
- Its waiting requests are cancelled. Requests that came through it, still waiting or approved but not yet running, show as Cancelled in Approvals, and their agents get
rejectedwithgateway_retired. - For a hosted Gateway, the tools of its connections are switched off, and Gatelion's hosted service stops running it.
- Its history stays. Its executions, approvals and audit trail are kept.
Retired Gateways are hidden from the list. Click Show retired Gateways (n) to see them; each shows Retired instead of the switch.
Versions and updates
Each row shows the Gateway's software version, once it has synced. When a newer version of the Gateway for your network is available, the row says update available with the new version number, like update available: v0.2.0. To update, see Upgrade. Settings, secrets and registration are kept.
The update notice is shown only for Gateways in your network.
Hosted Gateways
The MCP address
A hosted Gateway's row shows its MCP address with a copy button. Give this address to the agent's developer, together with an agent token. See Agents and tokens.
Set it up again with a new key
If you think a hosted Gateway's key may be compromised, click Set it up again with a new key on its row, then Set it up again. Its current key stops working at once, and Gatelion's hosted Gateway registers it again with a new key. The row shows Being set up by Gatelion… until that's done, which should take about a minute.
Agents keep the same MCP address and tokens, but their calls fail until it's set up again.
Related: Install a Gateway · Connect a system · Gateways and sync · Settings
Still stuck? Contact support from the console.