Install the Gameheim Agent: run Perforce and Git locally from the browser
For anyone on a Gameheim project who works with Perforce or Git: artists, designers, programmers and leads. This guide explains what the Gameheim Agent is, why it runs on your own computer, how to install and connect it, how updates work, where its logs live and what to do when it goes offline.
Why a web app needs a local agent to run Perforce commands
Perforce holds every asset and every revision of large Unreal Engine productions, at a scale few systems can match. To do that, it relies on a model where each person has a workspace on their own disk: a mapping between depot paths and local folders, with files that are opened, locked, shelved and submitted in changelists. Git with Git LFS works the same way at its core: the repository and the large binary files live in a working copy on your machine.
A browser cannot touch that disk. A web page cannot read the files in your workspace, open them for edit or write new revisions there. So a web tool for version control has two options: move the files through the cloud, or run the commands on the computer where the files already are.
For a game studio, moving file contents through a third-party cloud is a real cost. Builds and source assets are large, they are often under NDA, and many studios keep them on-premise on purpose. The second option keeps the files where they are and only sends back what the interface needs to show: names, states, changelist numbers, counts.
How the Gameheim Agent runs commands on your machine
The Gameheim Agent is a small desktop app that lives in your system tray. You use Gameheim in the browser; when you sync, check out, shelve, submit, commit or push, the cloud sends the command to your agent, the agent runs it on your computer against your Perforce server or Git remote, and it returns the result.
- File contents stay on your machine. The agent returns metadata: file names, states, changelist numbers and descriptions. Even a diff opens on a page the agent serves on your own computer, so its text never passes through the cloud.
- Outbound connection only. The agent opens an encrypted WebSocket to Gameheim. It does not open a port that the internet can reach; its local console listens only on your own computer.
- No extra client to install. The agent includes its own Java runtime, its own Perforce library and its own Git and Git LFS library. You do not need the p4 command line, P4V or a Git install for Gameheim to work.
- Your credentials, on your machine. Perforce passwords and Git tokens used by the agent are stored encrypted on your computer, protected by the operating system (DPAPI on Windows). Your Gameheim password is never stored by the agent.
- No administrator rights. The Windows installer is per-user and runs without elevation.
One agent for all your projects
When the agent signs in, it receives every project you can access in your organization. You do not install one agent per project. You can also install the agent on more than one computer (your plan may set a limit per user). A project is served by one of your machines at a time: the one that last worked on it. If that machine is offline, Gameheim sends the work to another of your agents that is online, which then takes the project over. Working on the same project from two machines at the same moment is not supported.
How to install and connect the agent in Gameheim
- A Gameheim account in your organization.
- A Windows 64-bit computer. The download page lists the platforms that are currently published.
- Your Perforce user and password, or a Git personal access token, for the project you will work on.
Download the installer
Open the agent download page and download the Windows
.msiinstaller. Each card shows the version and a SHA-256 checksum: compare it with the file you received if your studio verifies downloads. Windows SmartScreen may warn about the installer the first time.Run the installer
Run the
.msi. It installs for your Windows user only, lets you choose the folder, and adds a Gameheim entry to the Start menu. At the end you can launch the agent directly. A Gameheim icon appears in the system tray.Generate a setup code in Gameheim
In the browser, open Settings and then Agent. Under Connect a New Agent, click Generate Setup Code. You get a 6-digit code valid for 10 minutes, and the page shows when it expires.
Sign in from the agent wizard
The agent opens its setup wizard, Welcome to Gameheim Hub Agent. Enter your Gameheim Username and Password, and the 6-digit code in the OTP Code field, then click Connect.
Next the agent asks where your workspaces should live on disk. It suggests a
Gameheimfolder in your home directory; choose another folder if your projects need a faster or larger drive.Check that the agent is online
Back in Settings → Agent, the Gameheim Agent card shows your machine as Online, with Host, Version and Last heartbeat. The tray icon turns green when the agent is connected.
Set up your workspace
Open P4 Workspace (or Git Workspace for a Git project), enter your version control credentials for the project, and create a workspace or adopt one you already use in another client. See Perforce workspace setup for Unreal Engine and Git LFS for Unreal Engine.
How the agent updates
When a new version is published, the top bar of Gameheim shows Update to followed by the version number. Click it and Gameheim sends the update to every agent on your account that is older. An agent that is offline updates when it reconnects.
The agent verifies that the update is signed by Gameheim and that the file matches its checksum, then waits for running operations to finish (the badge shows Finishing current operations…), installs and restarts (Installing & restarting…). A long sync is not interrupted.
Sometimes a version is required. If your agent is below it, Perforce operations for that workspace are paused and a banner asks you to update; click Update agent to resume.
Moving a project from Perforce to Git needs version 1.1.0 or later on every computer that receives the project: from that version the agent retires the Perforce workspace at the cutover, keeping its files, and clones Git into a separate folder. The transition checklist names anyone whose agent is older. See move a project from Perforce to Git.
Where the agent logs and files are
| What | Windows location |
|---|---|
Logs (agent.log, rotated at 5 MB, 5 files kept) | %LOCALAPPDATA%\Gameheim\Agent\logs |
| Configuration, encrypted vault and local database | %LOCALAPPDATA%\Gameheim\Agent |
Logs stay on your machine; the agent does not upload them. If support asks for them, open the console, go to Settings and use Export Support Bundle → Download Bundle: it creates a zip with the recent logs that you can review before sending.
The agent starts automatically when you sign in to Windows, from your user's startup entries. To remove it, first Sign out in the agent and revoke it in Gameheim, then uninstall it from Windows Apps & features. Delete %LOCALAPPDATA%\Gameheim\Agent if you want to remove its local data as well.
Troubleshooting: agent offline, session expired, revoked
| What you see | What it means | What to do |
|---|---|---|
| Agent offline in Gameheim | The agent is not running, or cannot reach Gameheim. | Check the tray icon. Start the agent from the Start menu if it is missing. Commands are queued and run when the agent reconnects. |
| A Session expired banner in the agent dashboard, asking for an OTP to reconnect | The agent session lasts 14 days, then needs a fresh setup code. | Generate a new code in Settings → Agent, click Enter OTP and type it. Your folders and configuration are kept. |
| An Agent revoked banner asking for reconfiguration | The agent was revoked from Gameheim, by you or by a new sign-in replacing it. | Click Reconfigure Agent and sign in again with a new setup code. |
| The tray icon is yellow | The agent is paused. | Choose Resume Agent from the tray menu. |
| The console asks you to open it from the agent | You opened the local address directly, or another Windows user runs an agent on that port. | Use Control Panel in the tray menu. |
| The agent does not start | A start-up error. | Look at the latest agent.log and contact support with a support bundle. |
If you see a machine you do not recognise, open Settings → Security, then the Registered agents tab, revoke it and change your password. See audit log and account security.
Frequently asked questions
Does the Gameheim agent upload my Perforce files to the cloud?
No. The agent runs Perforce and Git commands on your own computer and sends back metadata: file names, states, changelist numbers and descriptions, counts. File contents stay on your machine: even diffs open on a page the agent serves locally.
Do I need P4V or the p4 command line to use Gameheim?
No. The agent includes its own Perforce library and its own Git and Git LFS library, plus a bundled Java runtime, so nothing else has to be installed. You can keep using P4V alongside Gameheim, and Gameheim can adopt a workspace you already created there.
Which operating systems does the Gameheim agent support?
Windows 64-bit, with a per-user .msi installer that does not need administrator rights and includes its own Java runtime. The agent download page lists the installers that are currently published for each platform, with the version and a SHA-256 checksum you can use to verify each file.
Do I need one agent per project?
No. One agent receives every project you can access in your organization. You can also install it on several computers, within the limit of your plan; each project is served by one of your machines at a time, and moves to another online agent if that machine is offline.
How long does an agent stay signed in?
An agent session lasts 14 days. After that the agent dashboard shows that a one-time code is required. Generate a new setup code in Settings, Agent, enter it in the agent and it reconnects with the same folders and configuration, without asking for your password again.