The OneSAM agent

Available

See every installed application and every piece of hardware on your computers, without visiting a single desk.

What you get

• A complete software list per computer: every installed application, its version and publisher.
• Hardware details for every machine: model, processor, memory, disks, graphics, network adapters and serial numbers.
• A picture that stays current: each computer reports on its own every 6 hours. Nobody has to remember to run anything.

How it works

The agent reports out; nothing connects in.

1. An admin downloads the installer for your company in OneSAM. It already contains your company’s key, so there is nothing to type.

2. You install it on each computer, one at a time or all at once with your deployment tool.

3. The agent runs quietly as a background service. It sends a report when it starts, then every 6 hours.

4. OneSAM recognises the software and hardware in each report. The computer appears under Devices, its applications under Installations, its components under Hardware fleet.

5. The agent checks once a day for a newer version of itself and asks the signed-in user before updating. The new version takes over the next time the computer restarts.

Basic actions

Download the installer

Only Admins and Superadmins can download the installer.

1. In OneSAM, click Install agent in the top bar.

2. Read the Terms and Conditions to the end, then tick the box to accept them on behalf of your company.

3. Choose Windows, macOS or Linux.

4. Click Download installer. Or click Generate shareable link to send the download to a colleague. A link works for 7 days and can be used three times.

Keep the installer private

The installer contains your company’s key. Anyone who has it can send reports into your company’s OneSAM. Share it only with the people who install it.

Install on a computer

Windows

1. Extract the ZIP to a folder. If Windows blocks the files, right-click the ZIP, choose Properties, tick Unblock, and extract again.

2. Double-click Install.cmd and approve the administrator prompt.

3. Wait for the message First report delivered to OneSAM. A local copy of the report is also saved on the Desktop, in a folder named <date>_onesam_report.

You don’t need to uninstall first. Running Install.cmd again connects an existing agent to your company.

macOS

Requires macOS 11 or later, on Apple silicon or Intel, and an administrator account.

1. Unzip the download.

2. In Terminal, go to the unzipped folder and run:

   sudo sh ./install.sh

3. If macOS blocks the file, allow it once under System Settings → Privacy & Security and run the command again.

Linux

Requires a 64-bit (x86_64) Linux with systemd, and root.

1. Extract the download:

   tar -xzf OneSAMAgent-*-linux-amd64.tar.gz

2. Run the installer:

   sudo sh ./install.sh

Install on many Windows computers at once

Use your deployment tool (Intune, Configuration Manager, Group Policy) with this command. Your company key is in the README.txt inside the ZIP.

msiexec /i "OneSAMAgent-<version>.msi" COMPANYKEY=<your-company-key> ACCEPTTERMS=1 /qn /norestart /l*v "%TEMP%\onesam-agent-install.log"

ACCEPTTERMS=1 is required. Without it a silent installation stops.

See the results

Open Devices in OneSAM. A computer appears as soon as its first report arrives.

• Devices: every computer and its operating system.
• Installations: every application, on which computer, in which version.
• Hardware fleet: processors, memory, disks and other components across all computers.

Computers without internet

Some computers must never connect to the internet. For those, the installer offers an offline mode: the agent writes the same report to the computer’s Desktop as onesam_report.html and onesam_report.json, and sends nothing.

For computers that can connect, always use the normal installation. A report uploaded by hand is a one-time snapshot and does not update.

Remove the agent

Windows

Uninstall OneSAM Agent in Settings → Apps, or run msiexec /x "OneSAMAgent-<version>.msi" /qn. Settings and logs stay in C:\ProgramData\OneSAMAgentNext; delete that folder to remove every trace.

macOS

sudo /usr/local/bin/onesamagent uninstall && sudo rm /usr/local/bin/onesamagent

Linux

sudo /usr/local/bin/onesamagent uninstall && sudo rm /usr/local/bin/onesamagent

The computer stays in OneSAM with its last report until an admin deletes it.

What it does not do

• It does not read your files, documents, emails, browser history, keystrokes or screen.
• It does not block, remove or change any software. It only reports.
• It does not see programs that were copied onto a computer without being installed, because the operating system has no record of them.
• It has no proxy setting. It needs a direct outbound HTTPS connection.

Privacy and security

• Outbound only. The agent sends reports over HTTPS (port 443). It opens no ports and accepts no incoming connections.
• Stored in the EU. Reports are stored in OneSAM’s database in the EU (Frankfurt).
• What it collects: operating system details, installed software, hardware components and their serial numbers, network adapters with their hardware (MAC) addresses, virtualisation details and Java runtimes.
• Names can appear. Windows keeps a “registered owner” name, which the agent reports. Software installed for a single user records that user’s Windows account ID and install folder, which can contain the user’s name.
• Safe updates. Updates download over HTTPS and are checked against a fingerprint (SHA-256) before they install. The signed-in user is asked first.
• Your company key is stored in the agent’s settings file on each computer. If you think it has leaked, contact OneSAM support to replace it.

Requirements

Windows	64-bit (x64), administrator rights
macOS	11 or later, Apple silicon or Intel, administrator rights
Linux	64-bit (x86_64) with systemd, root
Network	Outbound HTTPS (port 443) to yzmtkqviggniibmgsobe.supabase.co. On Windows the address is also in C:\ProgramData\OneSAMAgentNext\config.json as api_url.

FAQ

How often does a computer report?

When the agent starts, then every 6 hours. After the first report, each report waits a random few minutes (up to 15), so your computers don’t all report at the same moment.

Will people notice it?

It runs in the background with no window. Each report is limited to 10 minutes. People see the agent only when a new version is ready: a prompt asks them to approve the update.

What if a computer is offline for a while?

The agent keeps its latest report and sends a fresh one at the next report time once the connection is back. Old reports don’t pile up.

What if no one is signed in when an update is ready?

The update is skipped and offered again the next day. Agents in offline mode never update themselves.

Can I install it without anyone clicking anything?

Yes. Use the silent msiexec command above with your deployment tool.

Which firewall rules do I need?

Only outbound HTTPS (port 443) to the address under Requirements. Nothing inbound.

I installed the agent, but the computer doesn’t appear.

If no computer has reported within an hour of the last installer download, OneSAM shows Admins an amber notice on the Devices page. The most common cause is a firewall or proxy blocking outbound HTTPS. Run Install.cmd again as an administrator and look for First report delivered to OneSAM. If it doesn’t appear, send OneSAM support:

• %TEMP%\onesam-agent-install.log
• the contents of C:\ProgramData\OneSAMAgentNext\logs\
• C:\ProgramData\OneSAMAgentNext\config.json, with the company_key value deleted first

Who can download the installer?

Admins and Superadmins. Basic users don’t see the Install agent button.

Does uninstalling remove the computer from OneSAM?

No. The computer keeps its last report until an admin deletes it.