Agent build management

[Rambomst]

Summary

• Add an Agent builds catalog with file uploads, URL and GitHub imports, compatibility checks, usage counts, and archive/removal controls.
• Add per-device build selection, pin/hold/default update policies, installed-build identification, and deployment progress.
• Add controlled bulk deployments with canary batches and verification before proceeding.
• Replace bundled agent binaries with downloads from pinned GitHub releases, verified by size and SHA384 and cached for offline use.
• Add stable-release checks and download recovery controls. Release discovery and imports do not change defaults or deploy agents. Beta builds remain opt-in.
• Document the release format, configuration, and migration process. Public release downloads require no GitHub token; Actions artifacts and private imports require authentication.

Relates to:
Issue: #8176
MeshAgent PR: Ylianst/MeshAgent#426
MeshAgentAndroid PR: Ylianst/MeshCentralAndroidAgent#48

The legacy-1.2.6 migration releases must be published in Ylianst/MeshAgent and Ylianst/MeshCentralAndroidAgent before releasing MeshCentral with these defaults.

Please follow this checklist to avoid unnecessary back and forth (click to expand)

• 🧠 I used LLMs/AI in this contribution and reviewed all generated content.
  I understand that I am responsible for and able to explain every line of code I submit.
• 🔍 Any UI changes adhere to visual style of this project.
• 🛠️ I have self-reviewed and self-tested my code to ensure it works as expected.
• 🤖 I added or updated automated tests where appropriate.
• 📄 Documentation updates are included (if applicable).
• 🧰 Dependency updates are listed and explained.
• ⚠️ CI passes and is green.

Screenshots for Visual Changes

[si458]

the docs folder doesnt need changing or anything being added.
the should only be a simply single file in there to tell people to move to the new docs repo instead.
so you should add the docs to here instead https://github.com/Ylianst/MeshCentralDocs/tree/main
this is then accessible to ALL on https://docs.meshcentral.com

edit1: the is also WAY TOO MANY agent*.js files
can they not be merged into a single file?
agenttypes.js can stay put as we can use that to add new agents etc easier than inside the meshcentral.js!
good iea!

edit2: i keep seeing
MeshService64.exe: Release asset not found. Publish the configured release and asset before downloading it.
even tho i uploaded my own file?

edit3: clicking add agent then trying to download the 64 windows version results in a 404 file not found?

[Rambomst]

Your first comment and edit1 have been done.

I will look into edit2.

And for edit3, this is expected, currently they are placeholders until the files are bundled and published as a release on github.

[si458]

@Rambomst thank you!
but as for 3, i would of expected because i upload my own version, that when i click download it would download a customised version of that file but it didnt?
(imagine your a new user who has never used meshcentral before, so files dont exist etc)

[Rambomst]

Oh I thought you meant you were trying to add an agent from github, sure, if thats local then I will look into it.

[si458]

@Rambomst another idea, when u upload the exe/binary,
can we have check boxs to say

1. its fully customised (i built it manually myself and made changes),
   so DONT CHANGE ANYTHING, just download it directly as is with the .msh embedded oversally
2. needs self-signed code signing
3. i need it customising from my agentCustomise and agentfileinfo from config.json

then we could run the steps for 2 and 3 accordingly after upload rather than on startup every time!?

[Rambomst]

@si458 My latest commit includes fixes/changes for all the things you mentioned.

[si458]

@Rambomst hmm something isnt right?
i uploaded one before, then reuploaded but now its showing 2 of the same file?
they do have different hashes tho?
surely we should have a prompt saying 'this file already exists, would you like us to overwrite the existing file?'

[Rambomst]

If you sign it each time then the hashes will change but the Update hash should be the same.

There is also no duplicate check at the moment but I can add it if you want.

[si458]

@Rambomst ah ok got you! also just discovered the 'Manage Build' text to select which one u want as the default!
only thing is i dont know which one i made, which one was customised, which one was self-signed code signed etc
need to be able to identify that as i might want multiple builds etc!
dont worry about the overwritting

also still seeing all these messages

but im also seeing them in the warning of server tab too,

can we just have them in the server tab and not the in agent build tab?

[Rambomst]

Yeah I can make them appear in only that one spot. And you will continue to see those messages until github agent releases have been created for the old versions and sept 2026.

[Rambomst]

Both done in the latest commit. Let me know if you want more information exposed/changed.

[si458]

@Rambomst bug
if i set a default file for meshservice64.exe, and then delete the file, its still showing a default file?

edit: also got a random error?

could we maybe store the json as an object in the DB instead?
also means if its in the DB it can be encrypted too if we chose too

[Rambomst]

Defaults now live in the DB and point directly to the stored build, avoiding the executable replacement that caused the Windows error that you got.

Removing a default build now requires confirmation and clears its defaults. The records also support DB encryption when configured.

[si458]

@Rambomst ok amazing so far so good,
cant download because no agents, upload agents, cant download didnt set default, set default agent, now i can download!
just 1 problem is the customise (not code-sign)
i select ONLY CODE-SIGN on upload and its code-signed as expected,
BUT when i download an agent and run it, its customised!
from the looks of it, when i click download, its still adding into the .msh file the customise options, when in fact it should not be because i didnt say it was customised!
also when i set an installtext for my own info within the app window, that is in the .msh file too but under translations,
so im not sure how we go about that as translations are done on startup not while running?

[Rambomst]

@si458

The download handler was ignoring the builds customization flag. Both standard and customized translations are prepared at startup, then the correct set is selected for the build when downloading.

[si458]

ok works now thanks! but am i thick or not understanding the folders correctly?
uploaded 2 files

how do i know which is which when nothing matches?

[Rambomst]

@si458 The UI was hiding the build ID used for the folder name. It’s now shown with a copy button under Source, verification, and Manage build. You can also paste a folder name into the catalog filter to find its build.

[smartekIT]

hi guys,
I'm not sure if you are considering what people with EV SSL currently do to sign the agents like me for example, because i do have an extended validation ssl code sign certificate which requires me to use a usb-key hardware whenever i sign a file and doing it locally in windows then upload the signed files to the meshcentral linux server via ssh.

I have created a script to be used locally in windows to automate this for me while my usb-key always plugged in, the script runs if meshcentral get updated on the linux server, the script allows meshcentral to update normally then allow couple of minutes so MC can apply the customizations to the agents and sign them with that self-signed certificate on the MC server and get's them all placed in the meshcentral-data/signedagents. after that my local script take the rest, by:

downloading all the exe files from the signedagents folder using ssh --> sign those files with our EV SSL cert locally and apply server address lock to them --> upload the signed files via ssh to the meshcentral-data/signedagents.

now there is also another legacy location for the agents which my script also copy the signed files to on the server which is meshcentral-data/agents

the question is, after your implimentation, how should we work around that to have the files get the applied customizations based on the config then sign them locally with the lock enabled and upload them, because if your new feature will alter the uploaded files there, then it will invalidate our signed process and properly mess with the lock we applied. also you have stated that when MC get updated, it will look at this location and download the agents to it from the repo if not existed or compare the agents hashes there against the repo ones and download the repo ones if they are different. means we will always get our signed agents replaced or messed with if the MC work on them on every server startup.

it would be nice if you guys explain what people having the same scenario as me should do. because no matter what, we have to sign the files locally then upload them to the MC server as we have to physically use the usb-key to apply the cert and server address lock to those agents and instead of doing all of that manually, we rely on custom script to automate the process locally then upload it via ssh.

[si458]

@smartekIT we are still working on things and im doing alot of testing my side while @Rambomst does the coding
im in the same boat as you as my agents are signed with our cloud code-siging key so we have to run an app instead of a usb device

@Rambomst what we need is a DOWNLOAD button in the management page, so it downloads that agent as is directly

@smartekIT if @Rambomst does my step above it would help us,
meshcentral will download the agents from meshagent repo OR you upload your own
then you would download them from the agent build management page, then sign them, then reupload them and delete the non-signed versions (or keep the non-signed version you choice!)
you wont need to touch the agents or signedagents folder anymore as they would be stored in agentbuilds instead and all done through the web ui

@Rambomst can you have a look (seperate PR to this but can extend it) if we could maybe have a websocket api on the control.ashx for the agent build management page? this is NOT priority just a NICE thing to have maybe!

[smartekIT]

thanks @si458 and @Rambomst for the hard work you do, but my issue is exactly with what you said:

"you wont need to touch the agents or signedagents folder anymore as they would be stored in agentbuilds instead and all done through the web ui"

simply because i will have to do it manually thru the UI while it's better like what i'm doing now which relies on my automated script which does all the work automatically for me including i have created a AHK script to authenticate with the usb-key so i don't even need to type my cert password or do anything at all. so fully automated with no even a single manual upload! very fast and systematic (download -- sign -- upload -- restart MC service) all within seconds.

[si458]

@smartekIT ah right ok from my original testing the folder agents overwrites the new agentbuilds folder anyways when you go to download the agents!
i chased my tail for 5 mins originally cuz it was downloading the wrong agent until i decided to delete the folder and retest haha
but dont worry we we will still keep the agents folder for automation users (yourself) and ill look into the signedagents folder as this folder WAS used on startup to code-sign and customise the agent for users but oversally that wouldnt be used anymore because the new folder agentbuilds would be used instead!

we welcome more community feedback!

[smartekIT]

thanks @si458 ,
FYI I had this discussion with @Ylianst long time ago when he introduced the AuthinticodeJS in MC as before we used to sign our exe files then upload them to the agents folder. when he implemented AuthinticodeJS in MC it actually sign the agents during the first server restart and put them inside SignedAgents folder and i remember I asked him to specifically make the agents folder overwrites the SignedAgents folder so we don't have to change our existing scripts accordingly and thanks he did that. during AuthinticodeJS process the agents files, that time it applies the customization to them like logo, icon, ..etc.
so in my script if you remember i told you earlier that my scripts wait on MC couple of minutes after updates and restarts so it finishes the AuthinticodeJS work and place the customized agents in the SignedAgents folder, then my script kicks in to take those files, download them, sign and lock them, then upload them back to SignedAgents folder and Agents folder while actually it needs to upload them only to the agents folder but i did that way anyway to be safe. so the MC always checks the agents folder first as it overwrites all. and whatever in the SignedAgents folder is the applied customization agents but signed with the self-signed cert on the MC server.
if you are getting rid of the SignedAgents folder, then your agents i assume won't be having any customization and the custom icon and logo you specified in your config file!!

[si458]

we arent getting rid of anything! nothing will change how people use old methods!
the idea of signedagents was on startup meshcentral would customize the agent then code-sign it and put them in there
then the idea of agents was it had the HIGHEST priority and you could put anything you wanted in there exe/binary wise and it would use those instead
but the signedagents folder will ALWAYS change on every startup IF you change something in the config.json like say your companyname or filename or colour for example

[smartekIT]

this is why, my script process was 100% correct, taking the files after customizations from SignedAgents then sign them and upload them to folder Agents. this way our customized and signed agents will always overwrites and be in use by the server. as long this stays the case then all good.

Thanks @si458 and @Rambomst. at least now we all aware of what's going on and the correct steps for people having cases like me to follow.

[Rambomst]

Confirming what Simon said, with one exception: a build set as server default in the Agent builds tab outranks the agents folder. Nothing else does. The PR never touches the agents folder, and signedagents is still written only by the server's own signing pass, as before.

For the trigger list: startup re-signs when agentFileInfo (icon, logo, version info), the domain title, the signing cert or URL (including the ServerID lock) or the agent release itself changes. agentCustomization (companyName, fileName, colours) goes into the .msh at download time and never changes the signed binary, so a change there needs no new signing run.

One timing change: the default agents now download from the pinned release in the background at startup. Files that arrive after the server is up are signed and loaded as soon as they land, and the server logs it, so a fixed delay after an upgrade still works.

If you would rather have MeshCentral call you than poll it, externalSignJob (settings) runs with the output path after each server signing, at startup and now also for uploaded builds. A job that copies the file to your Windows box over ssh, runs signtool there and copies it back keeps the token and AHK where they are.

@si458 Download button is in.

[smartekIT]

my cmd script ssh and pull the files from signedagents folder locally to windows. ( with the help of WinScp command-line)
it fires AHK script to fill in the cert pass in windows prompt when signing using the usb-key and signtool.exe and apply the ServerID Lock.
it uploads back to agents folder in MC and issue meshcentral restart command all via SSH.

simple is that.

[smartekIT]

https://www.youtube.com/watch?v=xYtk85Bmc8Q

[smartekIT]

https://www.youtube.com/watch?v=qMAestNgCwc

[stephannn]

One stupid monk issue I see is when I open the GitHub settings by the arrow. The window don't just expand to the bottom, but also to top and moves all content up:

Another issue/question I have is, how can I upload the agent? I tried the service and console from the workflow, which I downloaded manually, but trying to upload it I get following message:

[Rambomst]

@stephannn Thanks for testing.

The dialog was recentering when GitHub settings expanded. I’ve fixed that and aligned the form fields.

I reproduced the upload error with NoAgentUpdate enabled. The importer was treating disabled updates as an unsupported agent type. Uploads now work while automatic updates stay disabled.