Skip to main content

Desktop Agent

The One Migrate desktop agent is a lightweight application that runs on a client machine and does the actual work: scanning source data, uploading files, tracking progress, and receiving commands from the cloud dashboard.

The agent communicates outbound only (HTTPS to api.theonemigrate.app). No inbound ports need to be opened.

Supported Platforms​

PlatformFormat
Windows (x64)MSI installer
macOS (Apple Silicon / Intel)DMG
Linux (x64).deb / .rpm

Download the agent from app.theonemigrate.app/downloads after logging in.

Registration Methods​

There are two ways to connect an agent to your Migrate account:

Best for: servers, headless VMs, or when you want to script deployment.

In the dashboard:

  1. Go to Settings → Headless Agent Registration.
  2. Enter an optional label (e.g., "Acme Corp DC Server") to identify the registration code.
  3. Click Generate Code.
  4. Copy the 8-character code. It expires in 24 hours and can only be used once.

On the client machine:

migrate-agent --register <CODE>

The agent exchanges the code for a permanent API key, registers itself, and connects immediately. The code is marked as used and cannot be re-used.

Scripted (silent) installation:

# Windows — install and register in one step
msiexec /i migrate-agent.msi /quiet REGISTER_CODE=<CODE>
# Linux
sudo dpkg -i migrate-agent.deb
migrate-agent --register <CODE> --service  # install as systemd service

Method 2: API Key (Manual)​

Best for: environments where you control agent configuration directly.

In the dashboard:

  1. Go to Settings → Agent Keys → enter a key name → click Generate.
  2. Copy the key immediately — it is shown only once.

On the agent machine: Set these environment variables before starting the agent:

MIGRATE_API_URL=https://api.theonemigrate.app
MIGRATE_AGENT_KEY=<your key>

Or set them in the agent config file:

[api]
url = https://api.theonemigrate.app
key = <your key>

Start the agent:

migrate-agent start

Agent Lifecycle​

After registration, the agent:

  1. Registers — POST /api/agents/register — creates or updates its agent record in your Migrate tenant.
  2. Heartbeats — POST /api/agents/{id}/heartbeat — every 2 minutes, reporting current status and active job ID. The heartbeat response delivers any pending commands from the dashboard.
  3. Polls commands — GET /api/agents/{id}/commands — every ~10 seconds between heartbeats, for faster command delivery.
  4. Reports progress — POST /api/progress — sends progress batches (files completed, bytes transferred, speed, errors) as the job runs.

An agent is marked Offline automatically if no heartbeat is received for 5 minutes.

Agent Statuses​

StatusMeaning
OnlineConnected and idle, ready for a new job
BusyCurrently executing a job
OfflineNo heartbeat in the last 5 minutes

Agent Commands​

From the dashboard (job detail page or Agents page), you can issue commands that deliver to the agent within ~10 seconds:

CommandEffect
PauseSuspends the current job; partial progress is preserved
ResumeResumes a paused job from where it left off
CancelStops the job; files already uploaded remain at destination

Revoking an Agent Key​

  1. Go to Settings → Agent Keys.
  2. Click the trash icon next to the key.
  3. Confirm revocation. The agent using that key is disconnected immediately on next API call.

To remove an agent record entirely:

  1. Go to Agents → click the agent.
  2. Click Delete Agent. This removes the agent from the dashboard. If the agent is still running with a valid key, it will re-register on next heartbeat.

Security​

  • Agent keys are SHA-256 hashed at rest. The full key is shown only at creation time.
  • Registration codes are single-use and expire in 24 hours.
  • Azure credentials are never stored on the agent. The agent calls GET /api/jobs/{id}/credentials to receive a 1-hour write-only SAS token scoped to the specific job container. Tokens are rotated before expiry.
  • All agent-to-API communication uses HTTPS with TLS 1.2+.
  • Each agent key is linked to a specific agent identity after registration, preventing key sharing across machines.

Agent Logs​

Logs are written locally to:

  • Windows: %PROGRAMDATA%\TheonemMigrate\logs\
  • macOS: ~/Library/Logs/theonemigrate/
  • Linux: /var/log/theonemigrate/

Log level can be set via the LOG_LEVEL environment variable (debug, info, warn, error). Default is info.