Configure the agent by hand
Everything the agent knows lives in one file, app_settings.json. The configurator writes
it for you, and for scripted or headless installs you can write it yourself. This page is
the field reference.
If you only want to connect a device, you do not need this page — link a device to your account is shorter and safer.
Where the file lives
The agent reads app_settings.json from the folder its own executable lives in. That
means:
- Windows — beside
FilemoteAgent.exe, in the install or portable folder. - A Linux service install —
/opt/filemote/app_settings.json, because that is where the install script puts the agent. - Anywhere else — beside the binary you launched.
The terminal configurator defaults to the file beside itself, and takes --config <path>
to edit a different one — which is exactly what a service install needs, since
FilemoteCli is not copied into the prefix. A relative path there is resolved against
your current directory.
Connection
| Field | Meaning |
|---|---|
ip | Server hostname or address the agent dials |
port | Server port |
EnforceHttps | Refuse to connect over plain HTTP. On by default; pairing through the terminal client turns it off, because the relay is reached over HTTP |
Leave ip and port pointing at your own server. An empty ip does not mean "figure it
out" — the agent falls back to a compiled-in default that is almost certainly not your
deployment.
Identity
| Field | Meaning |
|---|---|
login | Account e-mail |
pass | Encrypted account password — see below |
PairCode | A pairing code waiting to be redeemed |
DeviceToken | The durable token stored after a code is redeemed |
pass is not a plaintext password. The configurator stores it through the platform's
local protection — DPAPI on Windows, a local key file elsewhere — and the agent expects
that form. Pasting a plaintext password into the field will not work; set the password
through the configurator, or better, pair the device and leave pass empty.
What the agent may reach
rootPaths is the list of directories the browser is allowed to see. Everything outside it
is refused, including attempts to climb out with ... The agent refuses to start when the
list is empty, so this is not an optional field.
rootPath (singular) is a legacy field kept only so old settings files still load. Use
rootPaths.
Transfer tuning
| Field | Default | Meaning |
|---|---|---|
ChunkSizeKb | 64 | Size of each transfer chunk |
MaxDownloadMb | 2048 | Largest single download; 0 means unlimited |
ReconnectDelayMs | 5000 | First reconnect delay. It then doubles per attempt, with jitter, up to 30 seconds |
TransferSpeedLimitKbps | 0 | Outbound speed cap; 0 means unlimited |
AI and knowledge base
| Field | Default | Meaning |
|---|---|---|
AiModelId | qwen2.5-1.5b-instruct | The main model |
AiDevice | auto | auto picks the GPU when a Vulkan one is present; cpu and gpu force it. cuda is still accepted as a legacy value |
AiTemperature | 0.7 | Sampling temperature |
AiMaxNewTokens | 512 | Reply length cap |
AiSystemPrompt | empty | Prepended to every conversation |
AiAutoStart | false | Start the AI service with the agent |
AiDocumentModel, AiVisionModel, AiCodeModel, AiSummaryModel | empty | Specialist models; an empty slot falls back to the main model |
KbEnabled | true | Feed knowledge-base context into AI chat |
KbPaths | empty | Folders to index |
KbIncludeBrowser | false | Index browser history |
KbIncludeEmail | false | Index .eml and .msg files |
KbPrivacyAccepted | false | Records that the consent dialog was shown |
KbScheduleEnabled | false | Re-index on a schedule |
KbScheduleDays | unset | Days of the week to re-index on; an empty list means never |
KbScheduleTime | 03:00 | Time of day for the scheduled run, 24-hour |
KbScheduleIntervalHours still appears in older settings files. It is read only so those
files keep loading and no longer controls anything — the two fields above replaced it.
The AI service port is no longer configurable — it is fixed at 8765. Older settings files
may still contain an AiPort field; it is ignored.
Updates
| Field | Default | Meaning |
|---|---|---|
UpdateCheckEnabled | true | Master switch for update checking |
UpdateChannel | stable | stable or beta |
UpdateSkippedVersion | empty | The one version you chose to skip |
What those settings actually do is covered in keeping Filemote up to date.
Why pairing is still better
An agent configured with an account password derives your file-encryption key from that password. Change the password in the browser and the two sides stop agreeing: the browser derives the new key immediately while the running agent keeps the old one, and everything it sends back decrypts to nonsense. The symptom, and the fix, are in the device shows as offline.
Pairing avoids the whole problem by carrying the key in the code itself, out of band. Hand configuration exists for headless and scripted installs; if you have a screen and a browser, pair the device.
Updated 2026-07-31