Table of Contents

First-Time Setup

Last updated:

First-time setup creates the installation's one operator, connects Oscova to an AI engine, and prepares the main agent you will use in chat.

Note

Main agent means the default assistant Oscova creates for everyday chat. You can later edit its name, standing instruction, model provider, tools, skills, memory, and file access.

Before you start

  • Confirm the app can write to its local app data folder.
  • Decide whether you want a local model, Ollama, or a hosted provider such as OpenAI.
  • Keep the operator username and password somewhere safe.
  • Choose a separate Vault Password and store it somewhere safe because Oscova cannot recover it.
  • Create or gather API keys before configuring hosted providers.
  • Plan time for speech model downloads if you want local voice input or spoken replies.

Create the operator

When Oscova starts with no users, it shows Operator Setup instead of the normal sign-in screen. Enter the requested account details, including the required preferred name agents use when addressing you, and create the account. After the account exists, Oscova redirects to sign in.

This setup screen does not appear again while any user exists. If every user is removed from the database, Operator Setup appears again on the next launch.

The operator is also recorded as the host owner for local host-control features. Oscova attempts to write a local CLI access token when that account is created so the packaged oscova tool can talk to the same host without a separate login.

Restore an existing backup

Operator Setup can restore a .oscb backup before any users exist. Choose a backup up to 500 MB, enter the passphrase used during export, and wait while Oscova validates, stages, and restarts the host. Keep the browser open while it checks for the replacement host.

Restore replaces restorable app data such as users, agents, chats, settings, credentials, plugins, and each user's wrapped vault key. Machine-local authentication keys are not restored. Models, voices, logs, and pending restore files are also excluded.

Important

Restore is blocked once any user exists. Use a fresh installation or a fresh app-data folder when moving from a backup.

Complete onboarding

After first sign-in, Oscova requires you to create your Vault Password. It protects saved credentials and protected data, stays separate from the Account Password, and must be entered again after a restart or restore. After the vault is ready, onboarding guides your personal workspace through five steps:

  1. Language saves immediately and reloads the app in the selected language.
  2. Profile picture shows every packaged avatar with no initial selection. Choose one to continue. It is saved only when you select Continue.
  3. Model can configure any available first-party local or hosted provider.
  4. Speech can download local speech recognition and synthesis models. The checkboxes reveal the download cards. Click Download model on each card you want.
  5. Identity starts with Olivia and Friendly selected, then saves the main agent name and persona.

Onboarding cannot be closed without completing it. The profile-picture choice is required, but you can change it later from Your Profile, including uploading your own picture. Every other step reminds you that it can be skipped and completed later in Settings. Skip step moves forward without saving that step. If you select Skip all before choosing a profile picture, onboarding takes you to that required step. Afterward, Skip all marks onboarding complete without saving the agent identity. It does not undo choices already saved on earlier steps.

The model step presents a horizontally scrollable list in a stable order: Ollama, LM Studio, Local GGUF, Foundry Local, OpenAI, Anthropic, Google Gemini, Groq, NVIDIA NIM, and OpenRouter. Choices appear only when their provider runtime is available. Custom OpenAI-compatible connections remain available later in Model Providers settings.

Ollama and LM Studio require a valid HTTP or HTTPS base URL. Hosted providers require an API key. Select Fetch models, then choose a returned model. Keys stay only in memory during discovery and are saved when you select Continue. Changing the provider, key, or URL clears the fetched choice.

Local GGUF uses the default model configured for the app and can start its download. You can continue while that download is running. Foundry Local shows its model catalog, license details, and installation state. Download the selected model before continuing.

Skip step is the explicit way to continue without configuring a model provider. Chat stays paused until you finish a default provider in Settings.

Tip

You can skip voice during onboarding. The microphone, speaker, and hands-free buttons remain disabled until speech is ready later.

What to check next

  • Open chat and send a small test message.
  • If chat is paused, add or test a default model provider.
  • Review the main agent's instructions, tools, memory, and file access.
  • Add an embedding provider before depending on memory.
  • Configure credentials before enabling providers or integrations that need secrets.