Configuration

Aspected is configured via a JSON or YAML configuration file and/or environment variables. On startup the server loads configuration from the following sources (in order, later sources override earlier ones):

1. config.yaml / config.yml / config.json (in the working directory)
2. {APP_RUN_MODE}.yaml / {APP_RUN_MODE}.yml / {APP_RUN_MODE}.json (defaults to development)
3. local.yaml / local.yml / local.json
4. Environment variables prefixed with ASPECTED_

You can also pass a specific config file with the --config / -c flag:

./aspected-server --config /path/to/config.json

---

Configuration Reference

Below is the full configuration structure with default values:

config.yml

# Logging settings
log:
  level: info             # Minimum log level: trace, debug, info, warn, err, critical, off
  file:
    enabled: false        # Enable logging to a rotating file
    path: ./logs/app.log  # Path to the log file
    level: null           # Override log level for the file sink (defaults to log.level)
    sizeThresholdMb: 5    # Max size (MB) of a single log file before rotation
    maxFiles: 3           # Number of rotated log files to keep

# HTTP server settings
server:
  host: 0.0.0.0           # Address to bind the HTTP server to
  port: 8080              # Port to listen on
  corsEnabled: false      # Enable CORS headers on responses
  staticApiToken: ""      # Static API token for authentication (empty = no auth)
  https:
    enabled: false        # Enable HTTPS
    certificatePath: ""   # Path to the TLS certificate file (PEM)
    privateKeyPath: ""    # Path to the TLS private key file (PEM)

# Index storage settings
index:
  storagePath: ./data     # Directory where index data is persisted to disk

# Llama / text resolver settings (GGUF embedding models)
llama:
  modelsPath: ./models    # Directory containing GGUF model files
  useGpu: true            # Offload model layers to the GPU (if available)
  gpuLayers: -1           # Number of layers to offload to GPU (-1 = all layers)
  threads: -1             # CPU threads for inference (-1 = default, 4 threads)
  concurrentContexts: 4   # Number of concurrent inference contexts per model
  maxBatchSize: 2048      # Max tokens per batch (capped to model's context window)

---

Logging (log)

Key	Type	Default	Description
log.level	string	"info"	Minimum log level: trace, debug, info, warn, err, critical, off.
log.file.enabled	boolean	false	Enable logging to a rotating file.
log.file.path	string	"./logs/app.log"	Path to the log file.
log.file.level	string	(same as log.level)	Override log level for the file sink.
log.file.sizeThresholdMb	integer	5	Maximum size (MB) of a single log file before rotation.
log.file.maxFiles	integer	3	Number of rotated log files to keep.

Server (server)

Key	Type	Default	Description
server.host	string	"0.0.0.0"	Address to bind the HTTP server to.
server.port	integer	8080	Port to listen on.
server.corsEnabled	boolean	false	Enable CORS headers on responses.
server.staticApiToken	string	—	Static API token for request authentication. Empty disables.
server.https.enabled	boolean	false	Enable HTTPS / TLS on the server.
server.https.certificatePath	string	—	Path to the TLS certificate file (PEM).
server.https.privateKeyPath	string	—	Path to the TLS private key file (PEM).

Index Storage (index)

Key	Type	Default	Description
index.storagePath	string	"./data"	Directory where index data is persisted to disk.

Llama / Text Resolver (llama)

These settings control how the text resolver loads and runs GGUF embedding models.

Key	Type	Default	Description
llama.modelsPath	string	"./models"	Directory containing GGUF model files.
llama.useGpu	boolean	true	Offload model layers to the GPU (if available).
llama.gpuLayers	integer	-1	Number of layers to offload to the GPU. -1 means all layers.
llama.threads	integer	-1	Number of CPU threads for inference. -1 uses the default (4 threads).
llama.concurrentContexts	integer	4	Number of concurrent inference contexts per loaded model.
llama.maxBatchSize	integer	2048	Maximum number of tokens processed in a single batch. Capped to the model's context window size.

---

Environment Variables

Every configuration key can be set via an environment variable. Use the prefix ASPECTED followed by underscores (_) to separate nested keys, for example:

Config key	Environment variable
server.port	ASPECTED_SERVER_PORT
server.staticApiToken	ASPECTED_SERVER_STATIC_API_TOKEN
server.https.enabled	ASPECTED_SERVER_HTTPS_ENABLED
log.level	ASPECTED_LOG_LEVEL
log.file.enabled	ASPECTED_LOG_FILE_ENABLED
llama.modelsPath	ASPECTED_LLAMA_MODELS_PATH
llama.concurrentContexts	ASPECTED_LLAMA_CONCURRENT_CONTEXTS
index.storagePath	ASPECTED_INDEX_STORAGE_PATH

Docker Example

docker run -p 9090:9090 \
  -e ASPECTED_SERVER_PORT=9090 \
  -e ASPECTED_LOG_LEVEL=debug \
  -e ASPECTED_LLAMA_MODELS_PATH=/models \
  -v $(pwd)/models:/models \
  -v $(pwd)/data:/app/data \
  aspected:latest

---

Version Information

To print the server version and exit:

./aspected-server --version