First run

What setup asks, how to choose an AI account, what to connect next, and which command fixes an unfinished setup.

Setup has one required step: connect an AI account. Everything else, such as email, calendars, messaging apps, and your phone, can wait until after your first chat.

#What setup does

Whether you use a setup app or oktapod onboard in a terminal, first-run setup:

1. connects one AI account;
2. starts Oktapod as a background service;
3. turns on the private web app, reachable only from this computer, or from your Tailscale devices when Tailscale is already running;
4. checks that the agent answers; and
5. prints the web app address, oktapod ui --open, and oktapod chat "hello".

In a terminal, the default QuickStart asks as little as possible. If this computer already has a Codex, Claude, or Gemini command-line login, or an API key in the environment, it is offered first and Enter reuses it.

#Choose an AI account

Oktapod does not include an AI model. It uses the account you connect.

Other providers, such as Azure OpenAI, appear in the full list. After setup, Oktapod picks a fast, balanced, or deep model from your provider for each task. See Models and routing.

You can add a second provider as a fallback later, from Settings → Advanced → System setup or with oktapod onboard --manual.

#After your first chat

Add what you need, in any order:

• Your apps. Ask "Connect my Google calendar", or open Connections. See Connect your apps.
• A messaging app. Reach Oktapod from Telegram, WhatsApp, and others. See Messaging channels.
• Your phone. Install the iPhone or Android app, or add the web app to your home screen. See Phone apps.
• Its personality. Open Settings → General → Edit personality and describe how you want it to talk to you.

Personal onboarding is optional. Oktapod learns as you go; run oktapod onboard again whenever you want a guided session. It uses its own conversation, so it never takes over your normal chat.

#Reach it from other devices

Setup keeps Oktapod on this computer and does not open a public port. To use it from your phone or another computer, use Tailscale, a private network for your devices:

oktapod onboard --control-ui tailscale

Oktapod stays on this computer and Tailscale publishes the web app to your own devices over HTTPS. See Private web access for other options.

#Approvals are always on

Setup always starts in the standard approval mode. There is no global bypass; options such as --approval-mode bypass or --bypass-approvals are refused with an error.

When you need a short exception, for example to let one task make one kind of change to one place without asking, issue a scoped authority fuse:

oktapod authority fuse --effect <exact effect> --resource <exact resource> --minutes <1-60> --reason <text>

A fuse covers one exact effect on one exact resource, expires within an hour, and must be reviewed with oktapod authority review <fuse_id> before another fuse can be issued. See Approvals and safety.

#Which command do I need?

Most setup and repair happens in the web app under Settings → Advanced → System setup. In a terminal:

If a check reports that another process is holding Oktapod's port, run:

oktapod runtime repair
oktapod up

runtime repair clears stale state on its own. If a different program is using the port, it prints the command to find it; it never stops that program for you.

When a check still fails, see Troubleshooting.