First operating configuration

according to Rapid deployment After pulling the container, there are no users, channels and models in the system.This page follows the entire configuration from "empty system" to "send the first message": create administrators, add upstream channels, create models, set default models and task models, configure embedding models, and finally a few optional enhancements.

Step 1: Create an Administrator Account

The browser opens your site. automatically goes to the first-run setup page when new deployment (user number is 0) /setup Fill out three fields:

The field	Requested
The mailbox.	as an account.
The name	Showing name
The code	At least 8 characters.

Submitting this account. ** Become an administrator and log in automatically. ** No mail verification is required.

Setup has only one chance.

Once there is an account in the system, /setup It is permanently invalid (returns to 409). So do this as soon as possible after deployment is completed and don’t expose a “zero user” instance to the public web for a long time, otherwise anyone who visits it first can register as an administrator.

Subsequent user management (invitation, blocking, quota) is carried out in the admin console. Users and quota。

Step 2: Enter the admin console

There are two entries in the admin console, with the same effect:

• Management entry in the account menu at the bottom of the sidebar;
• direct visits /admin。

View all pages in the background. Overview of admin console The first configuration was mainly used for the two pages “Channels” and “Models”.

Step 3: Adding a channel

channel is a connection to an upstream model server. All server API Key is stored in the database’s channel table,** not written in .env Go to the channel Channels page in admin console, select the type and fill in the connection information when creating a new channel:

Type of channel	Applications of Upstream	need to fill.
Anthropic	Anthropic official or compatible services with its agreements	Base URL + API Key
OpenAI	OpenAI official or protocol-compatible services	Base URL + API Key
Gemini	Google Gemini	Base URL + API Key
OpenAI is compatible	Any transfer, aggregation or local reasoning service that exposes the OpenAI format interface	Base URL + API Key

The field explains:

• ** Type of ** Decide which protocol format Aivory calls upstream; select the official type with the official API; typically choose "OpenAI compatibility" with intermediate or custom reasoning services.
• Base URL The upstream service address.
• API Key API key issued by upstream, stored in the database.

A deployment can add multiple channels at the same time (such as an Anthropic official channel and an OpenAI-compatible switch), the channel itself is not visible to the average user, and the user will only see the "model" created next. Channel and Model。

Do you have an API key?

在 .env Inside set up ENABLE_MOCK_PROVIDER=true And restart, a built-in presentation channel and presentation model will be injected to end-to-end run through the entire conversation link. false。

Step 4: Creating a Model

After the channel is built, create a model entry that is visible to the user on the "model Models" page.

The field	Explained
The name	Showing the user’s model name in the model picker
Symbols	model icons in the selector and message stream
kind	Type of model: chat The Conversation /image (Image is generated) embedding (The quantity is embedded)
The channel	Which channel is called upstream?
Upstream Model ID	The real model ID to be transmitted to the upstream API must be consistent with the service provider’s model name.
Priced	The token single price of the model, used for the accounting of usage within the platform
vision	If image input is accepted, the user can send the image in the conversation of the model after opening it.
stream	Return of exports in a streamlined manner
tool_mode	Method of calling tools: native (upstream native tool calling) prompt (Called through a tipword analogue tool, suitable for upstream that does not support native function calling) none (This model does not use tools)
Study Switching	Is this model available for Deep Research, see Deep research

The model ** It appears immediately in the model picker for all users. ** It is recommended to start creating at least:

1. One main force. chat model (open the stream, set vision and tool_mode according to upstream capabilities);
2. A cheap and fast small model, the next step can be specified as a task model;
3. If you need a knowledge base, build one. embedding the model (see step 6).

Upstream Model ID Wrong Writing is the most common turning point.

The name is shown to the user and can be easily used; "upstream model ID" is actually sent to the service provider, spelling errors can cause the conversation to report the error directly.

Step 5: Set the default model and task model

After the model is built, assign three categories of global roles in the admin console:

Role is	Purpose of	recommended
The default model	Users' default choices when creating new conversations	Selecting a chat model
Task model	Small task calls within the system, not direct to the user	Choose a cheap, fast and stable model
The embedding model	Knowledge Base and Knowledge Base Function ** The necessary conditions **	See the 6th step.

Step 6: Configure an embedding model and enable the knowledge base

Knowledge Base (RAG) requires an embedding model to work.

** Path A, environmental variable (start period at the end) **: in deploy/.env Installed in EMBEDDING_BASE_URL / EMBEDDING_API_KEY / EMBEDDING_MODEL / EMBEDDING_DIM Refer to the OpenAI format. /v1/embeddings Endpoint and restart.

** Method B, admin console ** Creating one kind = embedding The model (go to a channel) and set it as an embedding model.

In any case, you should pay attention to the consistency of dimensions:

EMBEDDING_DIM must be consistent with the model output dimension

Qdrant uses a separate collection according to the embedded width. If the dimension configuration does not match the actual output of the model, the system returns the built-in 256-dimensional local embedder, its collection is incompatible with the 1536-dimensional model vector, and the quality of retrieval is only for development testing, not for production. text-embedding-3-small corresponding to EMBEDDING_DIM=1536。

When the embedding model is completely unconfigured, the knowledge base can still be created, and when vector retrieval is closed, the RAG returns to inject the entire document text within the scope into the context. The Knowledge Base Guide。

Step 7: Send the first message

Back to the chat interface:

1. Select the chat model you just created in the model picker.
2. Send a message confirming that you can receive a streamed response;
3. If the model has the vision enabled, you can send another image to authenticate multiple modules.
4. If tool_mode is not none It is possible to allow the model to do a network search or code execution, verify the tool link (need to complete the optional configuration below).

The order of checking when the error is: whether the upstream model ID is spelled correctly, and whether the channel Base URL/API Key is valid, docker compose logs app Specific Errors in Frequent Questions FAQ。

Selected configuration

The following three things do not affect the basic conversation, and you can open it as needed.

The Internet search.

Provide a web search tool to the model. Two configurations: admin console online configuration, or .env At the end of the period (SEARCH_PROVIDER / SEARCH_API_KEY / SEARCH_BASE_URL):

• serper / brave Fill the API key.
• searxng: Fill out the Base URL from the built instance, no key is required.

Internet search is also the foundation of Deep Research. Deep research。

The Sandbox Code

Docker Compose Complete Stack ** has been built. ** The sandbox service. app Share the built-in default API key with sandbox to execute Python code without any configuration. sandbox_base_url 与 sandbox_api_key The field ** for empty ** The built-in sandbox is only used.The two fields are filled only when connecting an external custom sandbox.

Sandbox Resource Limits, Network Isolation and Permanence Deployment of Sandbox See user side. The Python Sandbox。

Analysis of MinerU documents

Scanned and image-type PDFs require OCR to enter the knowledge base for retrieval. .env Configured MINERU_API_URL By admission https://mineru.net) and MINERU_API_KEY or configure online in the site settings of admin console, see Place set up. Only one line of positioning text is uploaded after such documents are not configured.

Moving from Old Examples

If you are moving from another set of Aivory instances, you do not need to manually rebuild the above configuration: generate a full-size migration package (including database logic backups, optional upload files and products, Qdrant vector data) on the old instance's admin console "Backup & Migration" page, then import to the same page of the new instance by importing the upper limit of size. MAX_BACKUP_BYTES Control, 20 GiB by default. complete process see Backup and Migration。

The next step.

• Reverse Proxy and HTTPS: app The container provides explicit HTTP, public network deployment must add TLS termination layer
• Cloudflare access Configuration points when exposing sites through Cloudflare
• Users and quota Set a daily message and image limit before registration.
• Conversation Functional Guide Send the manual to your users.
• Overview of admin console Other Background Capabilities