Getting Started¶

This guide will have you running Aspected in under five minutes using Docker.

Prerequisites¶

Docker installed on your machine.

1. Pull the Docker Image¶

First, download the latest Aspected image from Dockerhub:

CPUVulkanCUDA

docker pull xillio/aspected:latest

docker pull xillio/aspected:vulkan-latest

docker pull xillio/aspected:cuda-latest

Info

If your system has access to a GPU and you plan on using the text resolver, consider using one of the GPU-accelerated images (Vulkan or CUDA, depending on your system). Note that GPU acceleration requires additional parameters when starting the Docker container. See the GPU-Accelerated Embeddings section for details on setup and requirements.

Tip

You can also pin a specific version instead of latest, for example: xillio/aspected:0.2.0, xillio/aspected:vulkan-0.2.0, or xillio/aspected:cuda-0.2.0.

2. Run the Docker Image¶

Start the container, exposing the default port 8080:

CPUVulkanCUDA

docker run -p 8080:8080 xillio/aspected:latest

docker run -p 8080:8080 xillio/aspected:vulkan-latest

docker run -p 8080:8080 xillio/aspected:cuda-latest

You should see the Aspected ASCII banner followed by startup logs:

    _                        _           _
   / \   ___ _ __   ___  ___| |_ ___  __| |
  / _ \ / __| '_ \ / _ \/ __| __/ _ \/ _` |
 / ___ \\__ \ |_) |  __/ (__| ||  __/ (_| |
/_/   \_\___/ .__/ \___|\___|\__\___|\__,_|
            |_|

Version: ...

3. Verify the Server is Running¶

In another terminal, list the available indexes (there will be none yet):

curl http://localhost:8080/indexes

Expected response:

{
  "total": 0,
  "page": 1,
  "limit": 100,
  "data": [],
  "status": "ok"
}

The server is up and ready to accept requests.

Persistent Storage¶

By default, Aspected stores index data in a ./data directory inside the container. To persist indexes across container restarts, mount a host directory:

CPUVulkanCUDA

docker run -p 8080:8080 \
  -v $(pwd)/data:/app/data \
  xillio/aspected:latest

docker run -p 8080:8080 \
  -v $(pwd)/data:/app/data \
  xillio/aspected:vulkan-latest

docker run -p 8080:8080 \
  -v $(pwd)/data:/app/data \
  xillio/aspected:cuda-latest

Using the Text Resolver (Embedding Models)¶

If you plan to use the text resolver for semantic text embeddings, you need to make GGUF model files available to the server. See the Text Resolver page for details.

A quick way to get started is to download the embedding nomic-embed-text-v1.5.f16 model to the models/ directory and mount it in the container:

# Download the embedding model nomic-embed-text-v1.5.f16 to the models directory
mkdir -p models
wget -O models/nomic-embed-text-v1.5.f16.gguf \
  https://huggingface.co/nomic-ai/nomic-embed-text-v1.5-GGUF/resolve/main/nomic-embed-text-v1.5.f16.gguf

Then run the container with models mounted:

CPUVulkanCUDA

docker run -p 8080:8080 \
  -v $(pwd)/models:/app/models \
  -v $(pwd)/data:/app/data \
  xillio/aspected:latest

docker run -p 8080:8080 \
  -v $(pwd)/models:/app/models \
  -v $(pwd)/data:/app/data \
  xillio/aspected:vulkan-latest

docker run -p 8080:8080 \
  -v $(pwd)/models:/app/models \
  -v $(pwd)/data:/app/data \
  xillio/aspected:cuda-latest

GPU-Accelerated Embeddings¶

The Vulkan and CUDA images enable GPU acceleration for significantly faster text embeddings. Enabling GPU acceleration requires passing additional parameters to docker run so the container can access the host GPU.

Choosing an Image¶

Image	Best for	Requirements
Vulkan (`xillio/aspected:vulkan-latest`)	AMD and Intel GPUs, or NVIDIA GPUs with open-source drivers	Linux host with `/dev/kfd` and `/dev/dri` device nodes
CUDA (`xillio/aspected:cuda-latest`)	NVIDIA GPUs with proprietary drivers	Linux host with NVIDIA drivers and the NVIDIA Container Toolkit

Warning

The Vulkan image does not work with NVIDIA's proprietary drivers — only the open-source (Nouveau/NVK) drivers are supported. Even with open-source drivers on NVIDIA hardware, your mileage may vary. For NVIDIA GPUs, the CUDA image is the recommended choice.

Running with GPU¶

VulkanCUDA

Pass the GPU devices into the container with --device:

docker run -p 8080:8080 \
  -v $(pwd)/models:/app/models \
  -v $(pwd)/data:/app/data \
  --device /dev/kfd \
  --device /dev/dri \
  xillio/aspected:vulkan-latest

Note

Vulkan acceleration requires that the host has a compatible GPU and the appropriate kernel drivers installed. The /dev/kfd and /dev/dri device nodes must be present on the host system. The Vulkan Docker image ships with drivers for Intel, AMD, and NVIDIA GPUs and should be compatible with most devices, but you may encounter issues when running inside a virtual machine, as GPU passthrough and driver support can vary. For NVIDIA GPUs, only the open-source (Nouveau/NVK) drivers are supported.

Pass all GPUs into the container with --gpus all:

docker run -p 8080:8080 \
  -v $(pwd)/models:/app/models \
  -v $(pwd)/data:/app/data \
  --gpus all \
  xillio/aspected:cuda-latest

Note

CUDA acceleration requires that the host has an NVIDIA GPU with the appropriate NVIDIA drivers and the NVIDIA Container Toolkit installed.

Verifying GPU Detection¶

When the server starts, it logs the detected compute devices. If the GPU has been detected successfully, you should see output similar to:

VulkanCUDA

I 2026-06-10T13:53:07.970Z llama: Initialization complete (supported backends: CPU, Vulkan). Found 2 devices:
I 2026-06-10T13:53:07.970Z llama: 0 = Vulkan0 - AMD Radeon Graphics (RADV RENOIR) (type: iGPU, memory: 13.9 GiB free / 16.6 GiB total, id: 0000:05:00.0)
I 2026-06-10T13:53:07.970Z llama: 1 = CPU - AMD Ryzen 7 7730U with Radeon Graphics (type: CPU, memory: 29.2 GiB free / 29.2 GiB total)

I 2026-06-10T13:53:07.970Z llama: Initialization complete (supported backends: CPU, CUDA). Found 2 devices:
I 2026-06-10T13:53:07.970Z llama: 0 = CUDA0 - NVIDIA GeForce RTX 3080 (type: GPU, memory: 9.8 GiB free / 10.0 GiB total, id: 0000:01:00.0)
I 2026-06-10T13:53:07.970Z llama: 1 = CPU - AMD Ryzen 9 5900X 12-Core Processor (type: CPU, memory: 29.2 GiB free / 32.0 GiB total)

If only the CPU device is listed, the GPU was not detected. Verify that the correct --device or --gpus flags are being passed and that the host drivers are installed correctly.

Custom Configuration¶

You can supply a configuration file to override defaults (logging level, server port, model paths, etc.):

CPUVulkanCUDA

docker run -p 8080:8080 \
  -v $(pwd)/config.json:/app/config.json \
  -v $(pwd)/data:/app/data \
  xillio/aspected:latest

docker run -p 8080:8080 \
  -v $(pwd)/config.json:/app/config.json \
  -v $(pwd)/data:/app/data \
  xillio/aspected:vulkan-latest

docker run -p 8080:8080 \
  -v $(pwd)/config.json:/app/config.json \
  -v $(pwd)/data:/app/data \
  xillio/aspected:cuda-latest

See Configuration for all available options.

You can also configure the server using environment variables. Environment variables are prefixed with ASPECTED and use underscores (_) to separate nested keys. For example:

CPUVulkanCUDA

docker run -p 9090:9090 \
  -e ASPECTED_SERVER_PORT=9090 \
  -e ASPECTED_LOG_LEVEL=debug \
  xillio/aspected:latest

docker run -p 9090:9090 \
  -e ASPECTED_SERVER_PORT=9090 \
  -e ASPECTED_LOG_LEVEL=debug \
  xillio/aspected:vulkan-latest

docker run -p 9090:9090 \
  -e ASPECTED_SERVER_PORT=9090 \
  -e ASPECTED_LOG_LEVEL=debug \
  xillio/aspected:cuda-latest

Next Steps¶

Follow the hands-on Tutorial to create, train, and search an index.
Learn about Resolvers to understand how data is converted into vectors.