Complete the setup wizard
Walk through every setup screen, understand its fields, and know which settings are saved, tested, or actually active.
On this page
After installing ABot and running npx abot start, open the address printed in the terminal. The default is http://127.0.0.1:5177. On a new installation, Home presents the setup wizard.
This walkthrough follows the packaged local Web UI in the public 1.8.1 source. Keep the terminal running throughout setup. You do not need to edit JSON or install a second Web UI.
Before filling in the form
Have the exact model ID and provider details ready. For Ollama, start its service and download the model first. For OpenAI, have an API key that can access the chosen model. ABot includes adapters for these providers; it does not supply model weights, accounts, or credits.
The normal sequence is Provider → Connection → Embedding → Plugins → Computer → Ready. Computer appears when the local setup service supplies that step. Embedding and companion setup can be deferred; the model connection cannot.
An existing installation can enter later in the sequence or ask you to complete a missing credential. Check existing setup checks the saved model catalog; it is not a command to erase the current installation. Complete setup on Home before trying to work around it by opening another workspace.
1. Provider: choose where the model runs
Under Connect your first model, select one provider card, then Continue.
| Choice | What you need | What the choice does not do |
|---|---|---|
| Ollama | A reachable Ollama service and an installed model | It does not install Ollama or download the model. |
| OpenAI | An API key and an accessible model ID | It does not create an account or make model usage free. |
Choose the provider you can test now. You can add more connections and profiles later under Models. Selecting another provider while editing setup clears the previous model ID so you do not accidentally reuse it for a different service.
Checkpoint: the next screen is Connection details, with fields appropriate to the selected provider.
2. Connection: name the model and its capacity
Fill in the shared fields first:
| Field | What to enter | Common mistake |
|---|---|---|
| Model ID | The exact ID supplied by the provider, including any required tag | Entering a friendly nickname, a placeholder, or a model that has not been downloaded |
| Context window (tokens) | A positive whole number supported by this model’s configuration | Treating the number as an upgrade to the model’s actual capacity |
The packaged starter profile uses 32,768 tokens. This is a starter value, not automatic detection of every model’s limits. Check the model’s actual capacity and available resources; larger Ollama context windows can need more memory. You can change the profile later in Models.
Model IDs cannot be empty or contain spaces. The form accepts provider-style punctuation such as :, /, _, and -, but rejects a value starting with --. Context capacity must be a positive safe whole number. Server-side validation can also report when the selected capacity is too small for the configured admission reserves; follow that message rather than increasing it beyond the model’s real capacity.
If you selected Ollama
Enter Ollama address as a plain HTTP or HTTPS origin, for example:
http://127.0.0.1:11434Do not append /api/tags, another path, credentials, a query string, or a fragment. The address is used by the Runtime, not by your browser. Inside a container, 127.0.0.1 refers to that container. Choose an address the Runtime can reach if Ollama runs elsewhere.
Before saving, a useful check from that same network environment is:
curl http://127.0.0.1:11434/api/tagsUse your actual origin. The response should include the exact model ID you entered. If it does not, install that model on the Ollama host before testing a conversation.
If you selected OpenAI
Enter API key. If a credential is already configured, the field is labeled API key (optional); leaving it blank keeps the saved key. Do not paste it into the Model ID, a chat message, or a JSON example.
The setup flow stores the key privately in the installation’s .env. It does not store the secret in runtime JSON or return the saved key to the browser. Using a hosted model later sends relevant request data to the provider and can incur provider charges.
Save the connection
Select Save connection. An unchanged existing connection can instead show Continue. Wait for the save to complete before navigating away.
Saving connection details does not make a paid generation request. It also does not prove that every model operation will succeed: your first conversation is the practical test. If the screen reports a changed configuration from another window, refresh and review the current values before retrying.
Checkpoint: the wizard advances to Add embedding. Your connection has been saved; remaining selections still need final application.
3. Embedding: configure memory, or skip it
This step is optional. Choose Skip for now if you only want to start chatting. Passive cross-conversation memory starts disabled and can be configured later under Memory → Setup.
To enable it now, complete these fields:
| Control | How to use it |
|---|---|
| Embedding provider | Select a saved connection, or an offered new OpenAI/Ollama connection. It need not be the same service as the chat model. |
| Embedding model ID | Enter a model that supports embeddings. A chat model name is not automatically a valid embedding model. |
| Discover models | On a configured provider, request its model list. The results are suggestions, not automatic installation. |
| API key (optional if already saved) | For OpenAI, leave blank to reuse a saved key, or enter the required credential. |
| Ollama address | For a new Ollama embedding connection, enter the reachable origin without a path. |
Ollama discovery can list installed models. If the provider does not support discovery, enter the ID manually; this is expected for OpenAI. ABot does not choose or download an embedding model for you.
Select Test and save. Unlike saving the chat connection, this sends a real embedding probe. A hosted embedding provider receives the probe and later text used for memory embeddings. A failed probe does not mean memory was enabled. Read the error, correct the endpoint/model/credential, and retry—or skip the step. A new provider connection can remain saved even when its memory probe fails; the UI reports that distinction.
If memory is already configured and the selection is unchanged, the button can show Continue without another test.
A successful onboarding embedding save enables core memory and disables the separate Memory plugin in the same configuration update. Existing plugin data is retained. Skipping or failing the embedding step leaves that plugin selection unchanged. Core memory and the explicit Memory plugin are different stores; see Memory.
Checkpoint: after a successful save, the wizard opens Plugins. If you skipped, the final summary should say Set up later for Embedding rather than implying that memory is active.
4. Plugins: reduce the available tools
The screen lists installed plugins, their descriptions, their declared tools, and the selected-tool count. In a fresh setup, installed plugins start selected subject to host compatibility. Review them instead of clicking through unchanged.
- Read a plugin’s purpose and platform notice.
- Clear the plugin’s checkbox if you do not want it available.
- For a plugin you keep, review its individual tool checkboxes.
- Wait for Selection saved. It will take effect when you finish setup.
- Select Continue.
A disabled parent plugin prevents selecting its children until you enable it. Existing global deny rules remain blockers; a checkbox does not silently remove them. Platform-incompatible tools do not become executable just because the package is listed.
These choices decide availability, not permission to perform every action. Sensitive actions still follow the request’s permission mode. For a first trial, keep only the tools needed by the task and use Ask in the conversation.
If selection fails to save, the previous saved selection remains shown. Use Reload selection if offered, resolve the error, and check again before continuing. There is no benefit to reinstalling the entire Runtime for a failed checkbox save.
5. Computer: prepare access only if needed
This step uses facts about the computer running the Runtime; the browser’s operating system alone does not determine the setup. Follow the action displayed for your deployment. You can defer optional companion pairing with Skip for now and return to Home → Computer access later.
On a native Mac, Connect this Mac uses the installed companion bundle. An existing connection can offer Repair Mac connection. When connecting a Mac to Docker or a forwarded Runtime, Connect a Mac displays a local command and a separate short-lived code. Keep that invitation private and run only the command produced by your own installation.
Review any OS permission preparation separately. A connected computer is not proof that Screen Recording, Accessibility, or every target application’s permission is ready. Follow the displayed route-specific instructions and recheck after changing permissions.
For other deployment paths, use the published computer setup instructions and the status shown by your version. Do not install an additional companion merely because a generic example mentions one.
Continue becomes available when a fresh readiness check allows it. A local-access presentation can differ from the paired-computer presentation. Connecting or preparing permissions does not start SPARK collection; its acknowledgment, activity permission, and Start controls are separate.
6. Ready: apply, then test
Review the summary of Provider, Model, Context window, Embedding, and the selected plugin count. Use Back to correct a choice before applying.
Select Finish setup. This is the application step; a saved setting alone is not necessarily active. When it succeeds, the screen says You’re ready, and the primary action becomes Start chatting. If an owner is busy or requires a separate restart, read the reported message and retry when appropriate instead of assuming completion.
Choose Start chatting, confirm the selected model and permission mode, then send a small request that does not modify files. A normal reply is the first end-to-end check. Continue with your first conversation and the Web UI walkthrough.