docs: add more context to Windows execution

[rafaeloledo]

• Creating tasks without the GUI
• Editing screenshots that mention --no-console (see fix(autostart): remove --no-console from Windows instructions (fixes #945) #955 )
• Workarounds on running without console pop-up (relates to Update autostart.rst #861 )

[tomasz1986]

I would suggest to change the order, i.e. put the existing graphical instructions first, and the command line instructions later. We link to this guide quite often from the forum, so I think it would be better not to overwhelm less tech-savvy users with command line on the first sight.

I'm also not sure if mentioning VBScript is really worth it, as it is on its way out and is going to be removed from Windows in the next few years (see https://techcommunity.microsoft.com/blog/windows-itpro-blog/vbscript-deprecation-timelines-and-next-steps/4148301).

[rafaeloledo]

@tomasz1986
Thank you for the suggestions. Can you please see the new changes? 🤗

[rafaeloledo]

@rasa Hello, something is missing to the merge?

[rasa]

Your schtasks example includes --no-console --no-browser but your
Powershell example doesn't. Perhaps it should, so the two examples mirror each other?

Also, isn't -File required? So: powershell -File <path to script>.ps1 ?

[rafaeloledo]

Windows Terminal and Default Console:
In modern Windows versions, particularly with Windows Terminal set as the default console application, the --no-console flag might not completely hide the console window. It might still appear and then minimize, or the flag might be ignored entirely.

https://forum.syncthing.net/t/win-10-and-11-updates-breaks-no-console/19142

I was trying the --no-console flag that only exists in the Windows version of the syncthing and faced some issues related.

Switching to the mentioned legacy mode may be discouraged, since Windows Terminal is being a default on all new installations.

Wrapping with a ps1 script works even on wt.exe pop-ups.

-File/-FilePath is not mandatory.

Start-Process
    [-FilePath] <string>
    [[-ArgumentList] <string[]>]
    [-WorkingDirectory <string>]
    [-PassThru]
    [-Verb <string>]
    [-WindowStyle <ProcessWindowStyle>]
    [-Wait]
    [-Environment <hashtable>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

https://learn.microsoft.com/pt-br/powershell/module/microsoft.powershell.management/start-process?view=powershell-7.5
https://learn.microsoft.com/pt-br/powershell/module/microsoft.powershell.management/start-process?view=powershell-5.1

If you give the path as a first argument, it assumes that is the -FilePath flag as you can see above.

[bt90]

Might also try conhost.exe --headless ...

[rafaeloledo]

Might also try conhost.exe --headless ...

I've not tested it. Feel free to contribute and do it. I don't have Windows installation on my PC right now...

[rasa]

-File/-FilePath is not mandatory.

I wasn't referring to Start-Process but to the powershell command itself:

powershell -File "<path to script>.ps1"

[tomasz1986]

It still works without -File, but I'm not sure if it implicitly defaults to -File script.ps1 or rather -Command script.ps1 🙃.

[rasa]

Not on my system:

If you want to skip the -File option, you need to use:
powershell .\script.ps1.

Better to just tell our readers to use the option, as <path to script> is vague, imho.

[rafaeloledo]

It still works without -File, but I'm not sure if it implicitly defaults to -File script.ps1 or rather -Command script.ps1 🙃.

Unfortunately @rasa example is what happening in my system too.

So, the -File flag is mandatory in this case.

[rafaeloledo]

-File/-FilePath is not mandatory.

I wasn't referring to Start-Process but to the powershell command itself:

powershell -File "<path to script>.ps1"

I can only find docs offline about powershell.exe. But, as you can see, even if it is treated as optional, you'll need to use the dot operator to resolve file paths. Using -File directly can be more user friendly considering that the operator is less known by non programmers.

[rafaeloledo]

Made some changes according to the suggestions. Please check #936. conhost.exe example may be unnecessary and duplication of that subject. @tomasz1986 will powershell example be sufficient? Both seems to be working, but i can't even find online docs for the additional command and both seems to work.

https://learn.microsoft.com/en-us/windows/console/definitions#console-host

User may be overhelmed similar to vbsript usage. Following a standardized approach with powershell may be the case and only mention other technologies when it not work IMHO. 🤗

[tomasz1986]

Just my opinion, but after looking at the PR, and also the other PR from #936, my feeling is that we may be getting a bit too in depth here. This goal of this section is to provide the user with a few methods that would let them start Syncthing automatically on startup/boot, not to teach them how to use the command line 😉.

At the moment, the existing instructions can be summarised as follows:

1. The "run at system startup" using Task Scheduler method still works and doesn't require any changes.
2. The "run at user logon" using Task Scheduler method is outdated and doesn't work in Windows 10/11 with Windows Terminal installed and set as the default console. It needs to be updated (e.g. to utilise conhost or powershell to do the window hiding job).
3. The "run at user logon using the Startup folder" method faces the same issue as the previous one. It also requires an update to actually hide the console window.
4. The "run as a service" method doesn't require any changes.

I'm not sure adding yet another entry just to explain how to use PowerShell with Task Scheduler is really the way to go. How about adding powershell -WindowStyle Hidden (or possibly conhost --headless) to the existing two methods that need to be updated anyway instead? The other #936 PR does it, but only as a note, while we actually need to update the current instructions themselves (including the screenshots).

[rafaeloledo]

@tomasz1986 thank you for the review. I'll be making changes to fit your suggestions. Since it's a complete rework of the docs instead of just another section, it may consume more time. @Shablone can help me merge the changes.

Click in the Files Changed, you can see the Edit button?

ASAP i'm making new commits with new screenshots as like as the current ones.

[tomasz1986]

@rafaeloledo My second point about the Task Scheduler was wrong. As in the instructions we always recommend to "Run whether user is logged on or not", Syncthing runs hidden in background with no need for any additional tweaks.

In the meantime, I have pushed a minimal PR to remove --no-console from the instructions completely (see #955). I replaced it with conhost.exe --headless in the Startup folder method, as it is more lightweight. Not sure if PowerShell is really necessary at this point. Maybe as a note that instead of conhost.exe --headless one can also use powershell.exe -WindowStyle Hidden?

[rafaeloledo]

Waiting for the merge of #955 to make more changes here and not break anything.

[rafaeloledo]

I've managed to make the service work as this:

syncthingw.ps1

Start-Process -FilePath "C:\dev\scoop\apps\syncthing\current\syncthing.exe" -ArgumentList "--no-browser" -WindowStyle Hidden

install-synthng-service.bator directly on terminal (as admin)

schtasks /create /sc ONLOGON /tn Syncthing /tr "powershell -File C:\\dotfiles\\win32\\syncthingw.ps1"

The thing is @tomasz1986 and @rasa: running with powershell.exe and Start-Process doesn't persist a runtime process of powershell. Under the hood, it's using conhost.exe. So, it's not more lighweight. Poweshell is the modern solution that wraps the old execution of conhost if needed with the .NET std lib.

[tomasz1986]

Yeah, so the question remains, is there any benefit of recommending PowerShell instead of conhost.exe --headless?

I think the schtasks part isn't really necessary, as we already describe how to create tasks via the GUI, so there is no need to complicate things further (and also clutter the Docs with Windows-specific stuff).

[rafaeloledo]

No sign of conhost deprecation. Both are working. The main purpose of recommending powershell is to the POSSIBILITY in the FUTURE of changes.

Since it's desired to not have schtasks explanation in the docs and powershell usage, i'm changing to just mentioning the subject. It's sufficient or you just want image changes?

[tomasz1986]

You've removed a bit much 😉. I've actually got an idea how to add the information with your actual PowerShell command, but #955 needs to be merged first for it to work.

[rafaeloledo]

I found one little breaking change using conhost together with schtasks. Current only working with powershell

The problem is:

schtasks /create /sc ONLOGON /tn Syncthing /tr "powershell -File C:\\dotfiles\\win32\\syncthingw.ps1"
schtasks /create /sc ONLOGON /tn Syncthing /tr "conhost --headless C:\\scoop\\apps\\syncthing\\current\\syncthing.exe --no-browser"

Both tasks parses powershell and conhost as the program/script.

If you want to use conhost WITH args, you'll also need to wrap the entire command within a bat or cmd.

syncthingw.bat

conhost --headless "C:\dev\scoop\apps\syncthing\current\syncthing.exe" --no-browser

So, when i register the conhost script i must give like this:

Which will result in a different registering through CLI

schtasks /create /sc ONLOGON /tn Syncthing /tr "C:\\dotfiles\\win32\\syncthingw.bat"

Using inside schtasks and using conhost --headless will pop-up the terminal even with the --headless argument.

If i click on the terminal that is popped, it closes. A visual annoying thing.

This visual glitch is not happening using powershell.exe interpreter.

Conclusion, even if directly calling conhost is legal, it's not well integrated with registry and backend execution as powershell.

[rafaeloledo]

2025-08-31.20-11-35.mp4

I thought that @echo off was needed here, then i added but it still happens

[Shablone]

From my experience, using PowerShell has the potential to create more headaches. I've run into restrictive execution policies, which can be really tricky.

I think the conhost solution is reasonable and pragmatic since it works without additional hurdles for now. In the long run, instead of having another workaround, it might be ideal if Syncthing itself had a proper native background mode with tray functionality or. so That would make these console workarounds unnecessary.

[rafaeloledo]

From my experience, using PowerShell has the potential to create more headaches. I've run into restrictive execution policies, which can be really tricky.

I think the conhost solution is reasonable and pragmatic since it works without additional hurdles for now. In the long run, instead of having another workaround, it might be ideal if Syncthing itself had a proper native background mode with tray functionality or. so That would make these console workarounds unnecessary.

@Shablone
I understand your point. Other programs like scoop already use ExecutionPolicy changes as premise

The current PR is aiming just for docs improving. I mean, we need to tell the user that, currently, the --no-console isn't working. And if we assume conhost as the default solution on all the docs, we also need to note him that only powershell is well integrated with task scheduler.

So, when someone made another PR with the tray changes, we could remove the old description and replace for the new solution.

BTW, i've good experience with powershell overall, even when embedding execution inside .NET applications.

scoop itself is entirely made with ps1 scripts.

As an example, i've made a C# program for a game which can automatically handle queues for auto accepting.

In the first versions i was using the old cmd command for getting the instance of WMIC. Microsoft deprecated it in favor of powershell

https://learn.microsoft.com/en-us/windows/win32/wmisdk/wmic

[rafaeloledo]

I've made two more tests with conhost --headless

With @echo off

2025-09-01.14-05-31.mp4

Without

2025-09-01.14-07-08.mp4

It's not affecting the terminal pop-up.

The only scenario when a terminal window doesn't pop-up is when i run the command as it is in an already existing instance.

Without knowing the Microsoft code, i suppose that the conhost process is being reutilized

And if i invoke the command directly and is not possible to detect it in the process tree, it gets respawn.

So, the problem is not within the task scheduler, but with conhost itself.

[Shablone]

I'm sorry for changing the subject:
We could also address the root cause directly.

The console flashes because Syncthing is built as a console application. We can create a separate build (e.g., windows-daemon) compiled as a Windows GUI application. This tells the OS not to allocate a console, eliminating the flash without any external tools.

I've tested this and it works. The change is minimal: conditionally add the -H=windowsgui linker flag for that specific build in build.go around line 903.

This would be a separate build to avoid breaking console functionality for the main binary. It's a clean, native solution for users who only run Syncthing as a service.

For windows we actually could ship both console and no-console by providing two files e.g.: syncthing.exe and syncthing-d.exe

[rafaeloledo]

Following @Shablone point, the service can only run with ExecutionPolicy changes as shown below

2025-09-01.14-37-13.mp4

Then, the user must run

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Or other permissive policy similar to scoop to be able to use powershell in my example.

[rafaeloledo]

I'm sorry for changing the subject: We could also address the root cause directly.

The console flashes because Syncthing is built as a console application. We can create a separate build (e.g., windows-daemon) compiled as a Windows GUI application. This tells the OS not to allocate a console, eliminating the flash without any external tools.

I've tested this and it works. The change is minimal: conditionally add the -H=windowsgui linker flag for that specific build in build.go around line 903.

This would be a separate build to avoid breaking console functionality for the main binary. It's a clean, native solution for users who only run Syncthing as a service.

For windows we actually could ship both console and no-console by providing two files e.g.: syncthing.exe and syncthing-d.exe

Good idea

Closing for the following reasons that have been discussed in this PR:

• Powershell service depends on the user running policy modifications commands, since syncthing aims to serve a wide public, it's desirable to only programmers run commands in terminal
• As suggested by @Shablone, we can aim to build the app without the application type of console but the gui type
• Changes related to conhost are opened in fix(autostart): remove --no-console from Windows instructions (fixes #945) #955 and fix(syncthing): add note about --no-console requiring Command Prompt #957
• Changes in images depends on the maintainers choosing wether to use powershell or conhost to not get cluttered, but even this decision can be resolved compiling the program with other flags and having a builtin solution inside the executable for tray spawn. It could reduce documentation instead of inscreasing, that i consider a better approach.

[rafaeloledo]

schtasks /create /sc ONLOGON /tn Syncthing /tr "powershell -File C:\\dotfiles\\win32\\syncthingw.ps1"

One additional detail here.

schtasks /create /sc ONLOGON /tn Syncthing /tr "powershell -ExecutionPolicy RemoteSigned -File C:\\dotfiles\\win32\\syncthingw.ps1"

You can specify the ExecutionPolicy directly in the command. So, the use don't need to change global settings.