FAQ
Starting the Hub
The port is already in use
The launcher reports the error and leaves the other process running. Start again with a free port, for example python start.py --desktop --port 18990. A client you run separately must use the same address.
Install or build failed
Open startup.log in the data directory to see the cause. Check your network or proxy, then run the same command again. Finished steps are reused. The launcher never skips a failed step to start a partial service.
I mistyped the password during first setup, or stopped halfway
Start again and you can finish creating the account. Once the account exists, the launcher does not ask for the password again or reset it.
The page stopped working after I closed the window
The Hub stops with the launcher window. Start it again. To keep it running in the background, use Docker or a production deployment.
The launcher won't use my directory
Choose an empty directory outside the source folder. The launcher does not overwrite files it did not create.
I forgot the administrator password
Do not delete the database to start over. Keep the data and use the administrator password recovery process. For Docker, python ops/self-host/deploy.py credentials shows only the first-boot password.
Client
The client can't connect
Check that the Hub is running and that the address on the sign-in page (Service connection · Change address) matches it, including the port. Enter the address only, without /api.
Another computer can't reach my Hub
A source Hub listens on 127.0.0.1, which only this computer can reach. For other computers, use Docker behind your own HTTPS proxy.
The client asks me to install and start a Runner
Open Settings → Agent management and follow the prompt. The Runner does the work on this computer.
AI work
Chats don't get a reply
Check that a model service is connected and a model is enabled in Model catalog, and that the client lists it in Settings → My models. See Configure a model and a harness (runtime).
A harness shows Not installed
Install it from Settings → Agent management. Only Pi is built in.
Still stuck?
Search GitHub Issues or open a bug report.
harness harnesses runtime runtimes 底座