Skip to content
myosicam.us

Install the Agent

The MyOsicam agent is a lightweight Go binary that runs as a systemd service on each of your OScam servers. It discovers your existing OScam instances, syncs them to the panel, and applies changes you make in the panel back to the server — without ever touching OScam’s own operation.

Install the agent once per OScam server directly from the panel UI. The panel generates a signed install token, connects over SSH, and deploys the agent — you do not need to run any command on the server manually.

If you haven’t installed the panel yet, start there: Install the Panel.

Agent OS requirements

The agent OS floor is different from the panel OS floor.

OSMinimum versionNotes
Ubuntu20.04 LTSUbuntu 20.04, 22.04, and 24.04 are all supported for the agent.
Debian12Supported on Debian 12 (Bookworm) with standard systemd.

The panel requires Ubuntu ≥ 22.04 or Debian 12. The agent runs on any of the above — including Ubuntu 20.04, which the panel installer does not support as a panel host.

What the agent does

Once installed and running, the agent:

  • Discovers all OScam instances on the server: reads every configuration file, user list, webif settings, and runtime state.
  • Syncs a structured snapshot of each instance back to the panel over HTTPS.
  • Registers itself with the panel on first start and sends a heartbeat every minute so the panel knows the server is reachable.
  • Applies changes from the panel: updates oscam.user and oscam.conf, then triggers a live WebIF reload — no OScam restart needed.
  • Supports remote operations: start, stop, restart, and reload of OScam instances on command from the panel.
  • Collects resource readings: CPU usage (%), RAM consumption (MB), disk usage (MB) — reported to the panel periodically.
  • Runs as a systemd service, restarting automatically if it crashes — without affecting OScam.

What the agent does NOT do

  • Does not replace OScam or modify how OScam runs. OScam continues to operate exactly as you configured it.
  • Does not need root for runtime operations. Only the one-time install step (which sets up the systemd service and a narrow sudoers rule) requires root.
  • Does not transmit subscriber card data, entitlement details, or any DVB decryption material to MyOsicam — only management-plane metadata leaves your server.
  • Does not open any inbound ports. All communication is outbound from the agent to the panel.
  • Is not a dependency for OScam: if the agent stops or the panel is unreachable, OScam keeps serving your subscribers without interruption.

Before you install

Make sure the following are true for the OScam server you want to add:

  1. OScam is already running on the server.
  2. The panel can reach the server over SSH — you need the server’s IP/hostname, SSH port (default 22), and root credentials (password or key).
  3. The server OS is supported — Ubuntu ≥ 20.04 or Debian 12 (see the table above).
  4. The server has outbound HTTPS access — the agent phones home to the panel over HTTPS; no inbound port changes are needed on the OScam server.

Installing the agent from the panel

The agent install is triggered entirely from the panel UI:

  1. Log into the panel at https://panel.example.com/login.
  2. Navigate to Servers (or Agents) in the sidebar.
  3. Click Add Server (or Install Agent).
  4. Enter the server’s SSH connection details:
    • Hostname or IP address
    • SSH port (default: 22)
    • Root username (default: root)
    • Root password or SSH private key
  5. Click Install. The panel:
    • Generates a short-lived, single-use install token.
    • Connects to the server over SSH as root.
    • Downloads the agent binary and installs it as a systemd service.
    • Passes the install token to the agent.
  6. The agent starts, presents the token to the panel on its first registration call, and is accepted.
  7. After registration the agent immediately begins the discovery and sync described below.

Root access is needed exactly once — during this SSH-based install. After the agent is installed and running it operates as its own unprivileged user; root is not involved in any routine operation.

What happens on first run (discovery and sync)

Once the agent registers, it immediately scans the server for OScam instances and sends a structured snapshot back to the panel. The snapshot includes:

  • OScam instance list — name, config path, working directory, PID file location.
  • Configuration summary — reader count, protocol ports, global settings from oscam.conf.
  • Reader and account (oscam.user) entries — usernames, enabled state, caid/ident lists.
  • WebIF endpoint — host, port, and current reachability status.
  • Runtime status — running / stopped, process ID, uptime.
  • Resource readings — CPU usage (%), RAM consumption (MB), disk usage (MB).

After the first sync, every OScam instance you already operate appears in your panel dashboard immediately — with no re-configuration, no migration, and no downtime. Your existing OScam setup keeps running exactly as-is.

Verifying the agent appears in the panel

After the install completes:

  1. In the panel, open the Servers (or Agents) list.
  2. Your new server should appear with status Online and a green heartbeat indicator.
  3. Open the server entry to see the list of discovered OScam instances.
  4. Each instance shows its runtime status (running / stopped), reader count, and last sync time.

If the server shows as Unreachable or no instances appear, see the troubleshooting section below.

Security: install tokens and bearer token authentication

Every install token is short-lived and single-use. The panel generates it just before the SSH install, and it expires shortly after. Once the agent uses it to register, the token is invalidated and cannot be replayed.

After registration, every request the agent sends to the panel — heartbeats, sync calls, and command-result reports — is authenticated by presenting the agent token as a Bearer token in the Authorization header (Authorization: Bearer <agent_token>). The panel verifies the token on every inbound request. A missing or incorrect token is rejected immediately, so intercepted traffic cannot be used to forge valid agent requests.

No inbound ports need to be opened on your OScam server. The agent always initiates the outbound HTTPS connection; the panel never connects directly back to the agent.

Common install failures and fixes

SymptomLikely causeFix
SSH connection refused / timeoutWrong IP, port, or a firewall blocking SSH from the panel.Verify the SSH details; check that the panel’s IP is allowed to reach the server on the SSH port.
Authentication failedWrong root password or key.Re-enter credentials. If using a key, paste the private key exactly as shown (including header/footer lines).
Unsupported OSServer OS is not Ubuntu ≥ 20.04 or Debian 12.Upgrade the server OS or use a supported distro.
Agent registered but no instances foundOScam is not running, or oscam.conf is not in a standard location.Start OScam on the server, then trigger a manual resync from the panel.
Agent install returns 401 UnauthorizedThe install token was already used, expired, or the panel and agent clocks are skewed.Trigger a fresh install from the panel UI to generate a new token. If the problem recurs check that the server’s clock is in sync (timedatectl status).
Server shows Unreachable after installAgent cannot reach the panel URL (firewall, DNS, or TLS error on the OScam server).On the OScam server, run curl -I https://panel.example.com to test outbound HTTPS. Fix any firewall or DNS issue blocking the connection.
systemd service fails to startDependency or permissions issue during install.On the OScam server run systemctl status myosicam-agent and journalctl -u myosicam-agent -n 50 to read the error.

Next steps

With the panel running and at least one agent synced, you have a working fleet. Explore what you can do next: