# Back up and restore an Agent Gateway > Download an encrypted backup of all Agent Gateway data from the dashboard, store it safely, and restore the gateway from it after a bad change or data loss. This guide downloads a full backup of an Agent Gateway’s data from the dashboard and restores the gateway from that backup. Both actions are on the Admin tab of the Settings page; see [Settings](/products/affinidi-trust-fabric/agent-gateway/reference/configuration/settings.md#backup-and-restore) for each field. A gateway’s surfaces, agent identities and their keys, secrets, and user accounts all live in its own storage. A backup lets you return the gateway to a known state after a change that went wrong, without rebuilding each surface and re-issuing each identity by hand. Use this guide when: - You are about to upgrade the gateway or make a large configuration change. - You want a regular backup of a gateway that handles production traffic. - A change went wrong and you need the gateway back as it was when you took a backup. A backup restores only onto a gateway with the same domain and backup encryption key, which in practice is the gateway it was taken from. To hand someone a copy of the gateway’s storage with personal data, keys, and secrets removed, use Export Storage on the same tab instead. ## Prerequisites - You are signed in to the Agent Gateway dashboard with the Administrator role. The Admin tab is shown to administrators only. - Secure storage for the backup file that your organisation controls, such as a secrets manager or an encrypted file store with restricted access. - For a restore: a backup file taken from this gateway, and a time when a short interruption to the gateway’s traffic is acceptable. ## What a backup contains A backup is one encrypted file, backup.agbak. It holds everything the gateway needs to return to the state it was in when you took it. | Included | Not included | | Surfaces, templates, policies, and all other configuration | Logs | | Agent identities and their private keys | System metrics, which the gateway regenerates while it runs | | Secrets, API keys, and certificates | | | User accounts, passkey registrations, sessions, and avatars | | | Metrics data and Trust Recorder statuses | | The file is encrypted with AES-256-GCM, and only a gateway with the same domain and backup encryption key accepts it for a restore. It still holds every key and secret the gateway uses, so treat it with the same care as those secrets. Handle the backup as a secret Store the backup file only in storage your organisation controls, with access limited to the people who administer the gateway. Move it over encrypted channels only, and delete any copies left in download folders or shared drives once it is stored. ## Back up the gateway Open the Admin tab In the dashboard sidebar, select Settings, then select the Admin tab. Download the backup In the Backup / Restore section, under Full Storage Backup, select Backup. The dashboard shows “Building full storage backup…” and then “Backup downloaded successfully!”. Your browser saves the file as backup.agbak. Store the backup Rename the file so you can tell backups apart, for example booking-gateway-2026-11-02.agbak. Keep the .agbak extension, because the restore accepts only .agbak and .tgwbak files. Move the file to your secure storage, then delete the copy in your download folder. ## Restore the gateway A restore replaces all of the gateway’s data with the backup’s contents. Anything created after the backup was taken, such as a new surface, identity, or user account, is gone after the restore. Back up the current state Follow [Back up the gateway](#back-up-the-gateway) first, so you hold a copy of the current state in case you need it again. If the restore fails partway, the gateway puts its previous data back automatically. It deletes that copy once the restore succeeds, so your own backup is the only copy of the current state. Choose the backup file On the Admin tab, under Restore from Backup, select Restore and choose the backup file. Backups from earlier releases with the .tgwbak extension are accepted too. Confirm the restore Your browser asks “Are you sure you want to restore from this backup?”. Select OK. The dashboard shows “Uploading backup and initiating restore…” and then “Backup uploaded. The service will restart to complete the restore.” Wait for the gateway to restart The gateway restarts twice: once to put the backup in place, and once more to run with the restored data. The dashboard and the gateway’s surfaces are unavailable during the restarts. When the dashboard loads again, sign in with an account that existed when the backup was taken. Accounts created after the backup are not restored. ## Confirm ### Test 1: backup request returns a backup.agbak file Select Backup on the Admin tab. Expected: the dashboard shows “Backup downloaded successfully!” and your browser saves a backup.agbak file larger than zero bytes. ### Test 2: Surfaces page after a restore returns the surfaces from the backup After the restore, sign in and open Surfaces in the sidebar. Expected: the list matches the surfaces the gateway had when the backup was taken. A surface created after the backup is not listed. ### Test 3: request through a restored surface returns the expected response Send the request you use to check a surface after a change, for example the test request from the [MCP surface starter](/products/affinidi-trust-fabric/agent-gateway/how-to-guides/setup/mcp-surface-starter.md). Expected: the same status code and response as when the backup was taken. ## Troubleshooting | Symptom | Likely cause | Fix | | The Admin tab is not shown on the Settings page. | Your account does not have the Administrator role. | Ask an administrator to change your role on the Users tab, or to run the backup or restore. | | The dashboard shows “Please select a .agbak or legacy .tgwbak backup file”. | The chosen file does not end in .agbak or .tgwbak, often because it was renamed. | Rename the file so it ends in .agbak, then choose it again. | | The restore fails with a message that includes “Backup validation failed”. | The backup was taken from a gateway with a different domain or backup encryption key, is damaged, or is not an Agent Gateway backup. | Choose a backup taken from this gateway. Compare the file with the copy in your secure storage if you suspect damage. | | The restore fails with “Backup archive exceeds the 64 MiB limit”. | The file is larger than the restore accepts. | Check that you chose an Agent Gateway backup, then contact Affinidi support. | | The backup fails with a message that includes “Backup failed”. | The gateway could not build the backup, for example because its data has grown past the 64 MiB backup limit. | Select Truncate Old Metrics Now on the Admin tab to remove metrics older than the retention period, which can reduce the backup’s size, then select Backup again. If it still fails, contact Affinidi support. | | The dashboard does not load again several minutes after a restore. | The gateway has not finished restarting, or the restore could not complete. | Reload the page after a few more minutes. If the dashboard still does not load, contact Affinidi support. | | A surface, identity, or user account is missing after a restore. | It was created after the backup was taken. | Recreate it, or restore the backup you took just before the restore if it holds the item. | ## Next steps - [Upgrade an Agent Gateway to the latest release](/products/affinidi-trust-fabric/agent-gateway/how-to-guides/operations/upgrade-agent-gateway.md): back up first, then move the gateway to a new release. - [Create your first surface](/products/affinidi-trust-fabric/agent-gateway/get-started/create-first-surface.md): rebuild or add a surface after a restore. ## Related - [Settings: Admin tab](/products/affinidi-trust-fabric/agent-gateway/reference/configuration/settings.md#admin-tab): every action on the tab, including Export Storage. - [Settings: Users tab](/products/affinidi-trust-fabric/agent-gateway/reference/configuration/settings.md#users-tab): roles, and who can back up and restore. - [Secrets](/products/affinidi-trust-fabric/agent-gateway/concepts/secrets.md): how the gateway stores the secrets a backup holds.