VolksAI Docs

Installation

Install VolksAI on any Linux server with a single command. The installer sets up PostgreSQL, nginx with TLS, and the VolksAI application as a systemd service.

curl -fsSL https://app.volksai.io/install.sh | bash

The installer will:

• Detect your architecture (x86_64 or ARM64)
• Install and configure PostgreSQL 17
• Set up nginx as a reverse proxy with a self-signed TLS certificate
• Download the latest VolksAI binary
• Create a systemd service for automatic startup

Once complete, VolksAI will be running at https://<your-server-ip>.

System Requirements

First Login

After installation, log in with the default root credentials:

Architecture

VolksAI consists of two main components:

• Nexus — The core application server. Serves the web UI, manages users, conversations, and routes AI requests to LLM nodes. Stores data in PostgreSQL.
• LLM Nodes — GPU machines running AI models. They register with Nexus and serve inference requests over mTLS. You can run as many as you need.

The web UI is bundled into the Nexus binary — no separate frontend deployment is needed. Nginx sits in front as a reverse proxy handling TLS termination.

Mutual TLS (mTLS)

All communication between Nexus and LLM nodes is secured with mutual TLS. Unlike standard TLS where only the server proves its identity, mTLS requires both sides to present certificates — ensuring that only authorized nodes can serve AI requests and only the real Nexus can send them.

Here's how it works:

• Nexus acts as a Certificate Authority (CA). On first startup, Nexus generates a root CA keypair and its own identity certificate, then persists them in the database. This means every Nexus instance in a cluster shares the same CA.
• Registration = certificate signing. When an LLM node registers via volknode register, it sends a Certificate Signing Request (CSR) to Nexus. Nexus signs it with the CA key and returns a certificate. The node now has a Nexus-trusted identity.
• Every inference request is mutually authenticated. When a user sends a chat message, Nexus connects to the LLM node over TLS. Nexus presents its own identity certificate, and the node presents the certificate it received during registration. Both sides verify the other's certificate against the shared CA. If either side can't prove its identity, the connection is refused.

This means:

• No API keys or bearer tokens are sent over the wire between Nexus and nodes
• A rogue server cannot impersonate an LLM node — it won't have a certificate signed by Nexus's CA
• A rogue client cannot send requests to your LLM nodes — it won't have Nexus's identity certificate
• Nodes can run on different networks, data centers, or cloud providers — as long as they can reach Nexus, mTLS handles the trust

LLM Nodes

LLM nodes are separate machines (typically with GPUs) that run AI models and serve them to Nexus.

Installing Volknode

curl -fsSL https://llmnode.volksai.io/install.sh | bash

Pulling a Model

Download the model weights to the node:

volknode pull --model deepseek-chat

Running the Model

Load the model into GPU memory:

volknode run --model deepseek-chat

Registering with Nexus

Use a Personal Access Token with the llm:manage scope to register the node:

volknode register \
  --app-url https://volksai.yourcompany.com \
  --url https://gpu-node-01.yourcompany.com:8443 \
  --personal-access-token vk_pat_... \
  --llm-model-alias "Deepseek"

Serving

Start serving the model over TLS so Nexus can send requests:

volknode serve --port 8443

Once registered and serving, the model will appear in the VolksAI chat UI for all users.

Third-Party AI Providers

Instead of running your own GPU nodes, you can connect VolksAI to third-party AI APIs (OpenAI, Deepseek, etc.).

Start Nexus with the third-party AI flags:

THIRD_PARTY_AI_API_KEY=sk-... \
THIRD_PARTY_AI_BASE_URL=https://api.deepseek.com \
nexus --with-third-party-ai \
  --third-party-model-name deepseek-chat \
  --third-party-model-alias "Deepseek"

This registers the third-party model on startup. Users can chat with it immediately — no GPU hardware required.

Users & Roles

VolksAI has two roles:

The root user is a superadmin created automatically during installation. It cannot be deleted.

Superadmins can create, edit, and delete users from the Users page in the web UI.

Personal Access Tokens

PATs provide programmatic access to the VolksAI API. They are scoped and time-limited.

Available Scopes

Creating a Token

Via the web UI: go to Profile → Personal Access Tokens → Create Token.

Via the API:

curl -b cookies.txt \
  -H 'Content-Type: application/json' \
  -d '{"name": "my-token", "scopeCodes": ["llm:manage"], "expiresAt": "2026-12-31T00:00:00Z"}' \
  https://volksai.yourcompany.com/iam/create-personal-access-token

Conversations

VolksAI provides a full-featured chat interface:

• Multi-turn conversations with full context
• Edit sent messages and regenerate AI responses
• Retry AI responses without editing your message
• Like/dislike messages for feedback
• Rename and delete conversations
• Markdown rendering with syntax highlighting in AI responses

Conversations persist across sessions — log out and back in, and your history is intact.

Streaming

AI responses are streamed token-by-token using Server-Sent Events (SSE). For smooth streaming through a reverse proxy, configure nginx:

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 86400s;
    proxy_send_timeout 86400s;
    add_header X-Accel-Buffering "no";

    # WebSocket support
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

The key directive is proxy_buffering off — without it, nginx batches tokens and responses appear choppy.

API Overview

VolksAI exposes an OpenAI-compatible REST API, so any tool, library, or application that works with OpenAI can point at your VolksAI instance instead — no code changes required.

Base URL: https://volksai.yourcompany.com/v1

Authentication

Authenticate API requests with a Personal Access Token in the Authorization header:

curl https://volksai.yourcompany.com/v1/chat/completions \
  -H "Authorization: Bearer vk_pat_..." \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-chat", "messages": [{"role": "user", "content": "Hello"}]}'

Create a token from the web UI (Profile → Personal Access Tokens) or see Personal Access Tokens.

API Endpoints

Chat Completions

Generate a response from the model. Supports streaming via Server-Sent Events.

{
  "model": "deepseek-chat",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is VolksAI?"}
  ],
  "stream": true
}

Set "stream": true to receive tokens as they are generated. The response follows the OpenAI SSE format with data: prefixed JSON chunks.

Models

List all models available on your VolksAI instance.

{
  "object": "list",
  "data": [
    {
      "id": "deepseek-chat",
      "object": "model",
      "owned_by": "volksai"
    }
  ]
}

SDK Compatibility

Point any OpenAI SDK at your VolksAI instance by changing the base URL:

from openai import OpenAI

client = OpenAI(
    base_url="https://volksai.yourcompany.com/v1",
    api_key="vk_pat_..."
)

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "Hello"}]
)
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://volksai.yourcompany.com/v1",
  apiKey: "vk_pat_..."
});

const completion = await client.chat.completions.create({
  model: "deepseek-chat",
  messages: [{ role: "user", content: "Hello" }]
});
console.log(completion.choices[0].message.content);

curl https://volksai.yourcompany.com/v1/chat/completions \
  -H "Authorization: Bearer vk_pat_..." \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-chat", "messages": [{"role": "user", "content": "Hello"}], "stream": false}'

Production Setup

For a production deployment, we recommend:

• A dedicated server with at least 16 GB of RAM and 2 CPU cores
• A domain name with DNS pointing to your server
• A real TLS certificate (Let's Encrypt via certbot)
• A strong database password

Replace the Self-Signed Certificate

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d volksai.yourcompany.com

Updating

To update to the latest version, re-run the install script:

curl -fsSL https://app.volksai.io/install.sh | bash

The installer detects the existing setup and updates the binary without touching your database or configuration.

Nginx & SSL

The installer creates an nginx config at /etc/nginx/sites-available/nexus. For production, update it with your domain and Let's Encrypt certificate:

server {
    listen 443 ssl;
    server_name volksai.yourcompany.com;

    ssl_certificate /etc/letsencrypt/live/volksai.yourcompany.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/volksai.yourcompany.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
        add_header X-Accel-Buffering "no";
    }
}

server {
    listen 80;
    server_name volksai.yourcompany.com;
    return 301 https://$host$request_uri;
}