Setup help
Fixes for problems while installing Oktapod, connecting an AI account, or connecting your phone for the first time.
This page covers getting Oktapod running for the first time. Once it runs, see Health and recovery for everyday problems.
Mac
| What you see | What to do |
|---|---|
| The download says it requires Apple Silicon | Oktapod runs on Macs with Apple Silicon (M1 or later). Intel Macs are not supported. |
| macOS asks whether to open an app from the internet | The Oktapod app is signed and notarized by Apple. Choose Open. |
| macOS asks for access to Documents or Desktop | Allow it if your notes or vault live there. Oktapod only reads inside the folders you choose. |
Windows
| What you see | What to do |
|---|---|
| "Windows protected your PC" | The setup app is not code-signed yet, so SmartScreen warns about it. Check the download first (see below), then choose More info → Run anyway. |
| You have a Windows on ARM PC | Use the x64 setup. Windows runs it through its built-in x64 emulation. |
| "An incomplete Oktapod installation already exists" | An earlier attempt stopped part way. Rename the folder %LOCALAPPDATA%\oktapod\repo to repo.old, then run the setup app again. Delete repo.old once Oktapod works. |
| "The runtime installed, but its local setup service did not become reachable" | Another program may be using port 8787 or 8788. Open PowerShell and run oktapod runtime repair, then oktapod up. It never stops a program it does not own; it tells you which one is in the way. |
To check a Windows download, compare its fingerprint with the matching line in
the release's SHA256SUMS file (linked from the download window):
Get-FileHash .\oktapod-<version>-windows-x64-setup.exeLinux
| What you see | What to do |
|---|---|
| The AppImage does not start | AppImages need FUSE 2. On Ubuntu 24.04 run sudo apt install libfuse2t64; on older releases, libfuse2. |
| Installing the DEB | Run sudo apt install ./oktapod-<version>-linux-x64-setup.deb (or the ARM64 file) so dependencies install too. |
| Oktapod stops when you log out | It needs a systemd --user service. Run loginctl enable-linger $USER so it keeps running. |
Connecting your AI account
| What you see | What to do |
|---|---|
| "Connect a model to start chatting." | No AI account is connected yet. Run oktapod onboard, or open System setup in the web app. |
| The ChatGPT sign-in page does not come back | Finish signing in in the browser window that opened, then return to setup. If it was closed, start the sign-in again. |
| An API key is rejected | Check it was copied whole and that the provider account has billing set up. API use is billed by that provider, separately from any chat plan. |
| "Another onboarding flow is already running" | Finish or cancel the other setup window first. |
See First run for the AI accounts you can use.
The phone app cannot connect
| What you see | What to do |
|---|---|
| "No agent found yet" | The phone and computer are not on the same network, or discovery is blocked. Type the agent's HTTPS or Tailscale address instead. |
| The address is refused | The apps only connect over HTTPS. Set up Tailscale access (oktapod onboard --control-ui tailscale) and use the address it prints. |
| It worked on Wi-Fi but not elsewhere | Keep the Tailscale app connected on the phone. |
| The pairing code is rejected | Codes last 10 minutes and work once. Make a new one under Settings → Devices → Connect a phone or browser. |
| No other device is connected to make a code | Choose Use an access key in the app and paste the key that oktapod ui prints on the computer. |
See Phone apps for the full steps.
Still stuck
On the computer that runs Oktapod, run:
oktapod version
oktapod checkupcheckup lists what works, what does not, and the next step for each problem.
Email support@oktapod.ai with what you were doing, the
version, and the reason codes it shows. Never send access keys, API keys, or
backups. See Sharing details with support.