Activating a Fing Agent with a code or link

A Fing Agent installed as a snap, in Docker or on a Raspberry Pi can be activated by typing a short activation code at setup.fing.com, without scanning the network from the Fing mobile app. The agent shows the code on its local status page and through a terminal command; you enter it in your browser while signed in to your Fing account, choose a destination, and confirm.

What activation with a code is

What you need to know about the code:

• It is eight characters long and displayed as XXXX-XXXX, for example KDPM-W7XG. The hyphen is optional when you type or paste it, upper and lower case both work, and the code never contains characters that are easy to confuse, such as 0 and O or 1 and I.
• It is valid for 10 minutes. An expired code stops working, and the agent fetches a new one the next time you open the page or run the command.
• It can be used once. After a successful activation it is spent.
• It only works from a signed-in Fing account, and activation never happens without your explicit confirmation on the website.

This article covers the standard flow, where to find the code on each installation type, what to do when activation fails, how to use codes for remote sites, and how to deactivate an agent from the web interface. The classic flow, scanning the network with the Fing mobile app, keeps working alongside the code flow.

Standard flow: open fingagent.local and follow the link

The quickest path needs a browser on the same network as the agent. From power-on to a running agent, it takes about a minute.

At the device

1. Power on the device or start the agent and give it a moment to connect to Fing. The agent only requests a code when someone asks for one, so nothing is shown until you open its page or run the command described in the next sections.
2. On a computer, tablet or phone connected to the same network, open http://fingagent.local/ in a browser. Type http:// explicitly: the page is served over plain HTTP, and Chrome and Edge may otherwise try https:// and fail with a connection error. Safari opens it directly.
3. The agent's status page shows the agent name, its serial number, version and platform, the current code in large type, the time left before a new code replaces it and an Activate now button. The page refreshes itself every ten seconds; you do not need to reload it. The first load can take a few seconds while the agent fetches a code.

In your browser

1. Click Activate now. Your browser opens setup.fing.com with the code pre-filled. If you are not signed in, sign in or create a Fing account first. The code is kept through sign-in.
2. On the Activate a Fing agent page, check the device preview: agent type, platform, version and partial serial number. Under Activate agent into, pick the destination. Your personal workspace is preselected. Each entry shows your role and how many agent slots are in use.
3. Click Activate agent, review the Confirm activation dialog and click Confirm & activate. The website waits for the device to acknowledge, which usually takes a few seconds.
4. On Agent activated, click Open web app to see the agent and its network. The workspace owner receives a confirmation email.

Within about ten seconds of your confirmation, the status page switches to 'Agent activated. This agent is active and scanning this network.' The agent keeps answering to fingagent.local for as long as it runs, activated or not, so the name keeps leading to this device.

If fingagent.local does not open

Snap installation: where the code and link appear

On a snap install (Ubuntu, Ubuntu Core, Raspberry Pi OS with snapd) the agent runs as the fing-agent snap. The code is available in three places. All of them are read-only: they show how to activate, they never activate anything themselves.

fing-agent.activate

Fing Agent  (serial FNG-2417-4K7C | v6.2.1 | snap)
  STATUS: not activated yet. To activate this agent:
    1. open   https://setup.fing.com
    2. enter  KDPM-W7XG
    or open pre-filled:  https://setup.fing.com/?code=KDPM-W7XG
    (code expires in ~9m 47s)

sudo snap logs fing-agent

Docker installation: where the code and link appear

In Docker the agent runs inside the container, and so does the status page. The official installation, whether through the compose file or the manual docker run command, names the container FingAgent and runs it in host network mode. The commands below assume that. If you named the container differently, use your name instead.

docker exec FingAgent fing-agent.activate

docker logs FingAgent | grep -E 'Local address|Attached'

Troubleshooting activation

Most problems fall into three groups: the code is no longer good, the plan has no room for another agent, or the agent itself is not reachable. The message on the website tells you which one you are in.

The code has expired or isn't accepted

'This code isn't valid' appears right after you enter the code. The website gives the same message whether the code was mistyped, expired or already used, so a stranger cannot probe which codes exist. Codes expire 10 minutes after they are issued, so a code copied from a screenshot or a message a while ago is usually stale.

1. Go back to the device: the status page or the fing-agent.activate command always shows the current code.
2. Enter the new code. If you came from a pre-filled link, replace the code on the page rather than re-opening the old link.

'Activation didn't complete. This code is no longer valid' appears after you clicked Confirm & activate. The code was still valid when the page checked it, but it expired before you confirmed. This typically happens when sign-up, a workspace change or a plan purchase took longer than 10 minutes. Click Enter a new code and use the code the device shows now.

'Too many attempts' means several codes failed in a row from your account. Wait a few minutes, then read the current code from the device and try once more.

Your plan has no free agent slots

Agent slots belong to the owner of the destination workspace and are shared across all workspaces that owner has. The page checks the slots as soon as it recognises the code, and again every time you change the destination, so you see the problem before confirming, not after.

When a purchase is the way forward, See plans replaces the Activate agent button and carries your code with it. When you finish on the plans page, a Complete agent activation button brings you back with the code pre-filled. Purchases often take longer than the 10-minute code lifetime, so if you then see 'This code isn't valid', read the fresh code from the device and continue. Your purchase is not affected.

If the message 'The agent limit was reached before this activation completed' appears after confirming, someone else used the last slot while you were confirming. Review the plan options and try again.

The agent is offline or can't be reached

Activation is completed by the agent itself: Fing pushes the activation to the device over its live connection and waits for an acknowledgement. If the device is not connected, activation cannot finish.

'The device is offline' appears under the device preview before you confirm. The agent has not reported to Fing for a while. Check that the device has power and network access, and that nothing blocks outbound TCP port 4443. Once it reconnects it shows a fresh code; the one you hold has most likely expired by then.

'Something went wrong on our side' appears after confirming. The push to the device failed for a temporary reason, most often because the agent was reconnecting at that moment, for example right after a restart or a deactivation. Your code is still valid. Wait a moment and click Try again. If it keeps failing, run fing-agent.activate on the device: a 'WARNING: not connected to the backend' line means the agent cannot reach Fing.

The device's status page says 'Agent activated' but you did not activate it. Someone else entered the code first, or the agent was previously activated into another account. The code is spent and the agent now belongs to that account. To move it, the current owner must deactivate it from the web interface (see the last section). The agent then shows a new code the next time its page is opened or its command is run.

The device shows no code at all. The agent has no connection to Fing, so no code can be issued; the status page shows an empty code field. The command prints 'no code available right now (agent not connected?)' in this state. Fix the connection first.

Activating agents on remote networks

The code separates two roles that the mobile-scan flow forces onto one person: someone with physical or remote access to the device reads the code, and the account holder redeems it from anywhere. This is what makes the flow useful for managed sites and for headless devices, which have no screen or keyboard of their own.

Ship a preloaded Raspberry Pi and have someone on site share the code

1. Prepare the Raspberry Pi with the Fing Agent image, or install the fing-agent snap, before shipping. Do not activate it. A device that was activated for testing must be deactivated first, otherwise it ships bound to your test workspace.
2. Ship the device. Ask the person on site to connect it to the network with an Ethernet cable and power it on.
3. Ask them to open http://fingagent.local/ on a laptop or phone connected to the same network and send you either the code shown on the page or the link behind Activate now. A photo of the page works too. Remind them the code is valid for 10 minutes, so they should send it as soon as it appears, and you should be ready to use it.
4. In your own browser, signed in to your Fing account, open setup.fing.com, enter the code or open the link, pick the customer's workspace as destination and confirm.
5. Tell the person on site that the page now reads 'Agent activated'. Nothing else is needed from them.

Two things to plan for. If the site cannot open fingagent.local, for example because the laptop is on guest Wi-Fi or the person is on Android, ask them to scan the network with the Fing app instead, which lists the agent and can activate it directly. And if a Fing Agent is already running on that network, activated or not, the new device answers to fingagent-2.local instead, then fingagent-3.local for the next one, because each agent keeps its name for as long as it runs. Ask the person on site to try the next number.

If you manage many sites, the JSON document at http://<device-ip>/activation lets a script collect codes from a batch of freshly imaged devices; the code still has to be entered on setup.fing.com by a signed-in user.

Use SSH or Remote Desktop to read the code, then activate from your own account

If you already administer the machine that runs the agent, you do not need anyone on site.

In both cases the agent ends up in the workspace you chose, with you or your organisation as owner, and the workspace owner receives the confirmation email. The remote machine never holds your Fing credentials.

Deactivating an agent from the web interface

Deactivating releases the agent from your account and frees its slot. The software stays installed on the device, and the device can be activated again with a new code, by you or by someone else. Use it when you retire a site, move an agent to another workspace or customer, or want to re-ship a device you used for testing.

1. Sign in to the Fing web app and open Account, then Sources. Each monitoring source has its own row.
2. On the row of the agent, open the … menu and choose Deactivate.
3. Read the Deactivate monitoring source? dialog. It warns that customised settings tied to this source, such as automatically blocked devices, scheduled downtime, speed tests and other monitoring configuration, may be removed, and that the device stays installed and can be activated again later with a new activation code.
4. Click Deactivate. A confirmation appears when the source has been deactivated, and the account owner receives an email.

What happens on the device:

• Fing drops the agent's connection and the agent reconnects automatically. Its log shows a DEACTIVATED line.
• The agent does not fetch a new code by itself. The next time someone opens its status page or runs fing-agent.activate, it requests one and shows it. If the status page was left open on the 'Agent activated' view, reload it: that view only refreshes itself once an hour.
• The agent keeps answering to the same fingagent.local name it claimed at start-up.
• Scanning stops until the agent is activated again. Network history that was tied to the deactivated source is not carried over to the new activation.