Unotusk Unotusk DOCS
Support
1.1 Introduction

Architecture Overview

Unotusk is a self-contained, single-tenant intelligence engine for engineering teams. Unlike cloud-hosted AI coding assistants that transmit source code and AST tokens to external multi-tenant infrastructure, Unotusk runs 100% within your private infrastructure.

Core Operating Invariants:
  • • Zero Cloud Egress: 0 packets leave your internal network during AST parsing, vector embedding search, and query grounding.
  • • Evidentiary Grounding: Every response includes verifiable citation chips pointing to exact file paths and line ranges. If code evidence does not exist, the engine declares the absence rather than hallucinating.
  • • Single-Tenant Local Stack: Deployed as a dedicated Server Node (PostgreSQL 16 + pgvector, Redis, FastAPI) communicating with native Desktop Clients over internal LAN HTTP REST (:8000).
1.2 Getting Started

3-Minute Quick Start Guide

Setting up Unotusk involves two straightforward steps: starting the local Server Node on a designated workstation or server, and pointing your team’s Desktop Clients to its internal IP address.

STEP 1: Launch Server Setup Wizard

On your host server or workstation, run the Server Setup Wizard. The wizard verifies Docker connectivity and port availability, then boots the stack:

$ ./setup_app
STEP 2: Verify Endpoint Status

Confirm the API engine is listening and connected to the database:

$ curl -s http://localhost:8000/api/v1/health
{ "status": "healthy", "database": "postgresql+pgvector", "redis": "connected" }
STEP 3: Connect Desktop Clients

Share the host machine's internal LAN IP (e.g. http://10.0.0.59:8000) with engineers. On first launch of the native macOS, Windows, or Linux desktop app, paste this endpoint to begin querying.

1.3 Hardware Sizing

Host System Requirements

Hardware sizing depends on the number of concurrent engineering repositories and total lines of code indexed.

Deployment Tier
vCPU
Memory
Disk
Capacity
Pilot / Local
2 Cores
4 GB
20 GB SSD
1–5 repos (<50k LOC)
Standard Team
4 Cores
8 GB
50 GB SSD
5–25 repos (<250k LOC)
Enterprise Core
8 Cores
16 GB
100 GB NVMe
25+ enterprise codebases
Host OS: Ubuntu 20.04+, Debian 11+, RHEL 8+, macOS 12+, or Windows 10/11 x64 with Docker Desktop or Docker Engine 24+.
2.1 Infrastructure

Server Node Setup

Automated Setup Wizard (GUI)

The Setup Wizard is recommended for Windows Server hosts and desktop workstations. It handles container orchestration, pre-flight port checks, and database migrations with single-click verification.

Downloads:

Headless Linux Deployment (Docker Compose)

For headless Ubuntu, Debian, or enterprise servers, run the stack directly with Docker Compose: 

# 1. Start backend services
docker compose up -d

# 2. Check running container status
docker compose ps

# 3. View live FastAPI backend logs
docker compose logs -f api

Port Allocation

Port
Protocol
Service
:8000
HTTP REST / WS
FastAPI Intelligence Core (Client Ingress)
:5432
TCP / SQL
PostgreSQL 16 + pgvector (Internal only)
:6379
TCP
Redis 7 Task Broker (Internal only)
3.1 Client Experience

Desktop Client Guide

The Desktop Client is the primary interface for software engineers and architects. It communicates directly with your local server node without passing through third-party servers.

Evidentiary Grounded Ask

Press Ctrl + K to open Grounded Ask. Type any architecture or implementation question:

Example Queries:
  • • "Where are incoming HTTP requests authenticated?"
  • • "Which modules have direct dependencies on the payment gateway?"
  • • "Trace the execution flow from route dispatch to database commit."

Proactive Discovery Analyzers

Upon repository ingestion, Unotusk runs 9 deterministic structural analyzers across the parsed AST:

  • Circular Dependency Detection: Uncovers import cycles across packages.
  • Component Coupling: Highlights tightly-coupled classes and God objects.
  • Test Coverage Gaps: Identifies public interfaces with zero associated unit test specs.
  • Security Boundary Violations: Detects unvalidated parameters in controller actions.
4.1 Security & Isolation

Systems Architecture & Data Isolation

Unotusk is designed for air-gapped security protocols. The system contains an offline deterministic synthesizer fallback, allowing complete codebase navigation and AST traversal with zero external internet connectivity.

Data Storage & Encryption:

Relational schemas and vector chunk embeddings are stored in PostgreSQL 16 utilizing the pgvector extension with HNSW indexing. Code chunks and symbol references never leave the PostgreSQL database container.

Database connection: postgresql://postgres:<POSTGRES_PASSWORD>@postgres:5432/unotusk_db
5.1 Operations Runbook

Troubleshooting & Operations

Port 8000 Conflict Resolution

If another service (e.g. an existing development server or internal proxy) binds to port 8000: 

# 1. Identify conflicting process
sudo lsof -i :8000

# 2. Or rebind Unotusk port in .env
API_PORT=8080

# 3. Restart stack
docker compose up -d

Health & Diagnostic Logs

Unotusk automatically redacts all credentials, tokens, and passwords in all logs. To export complete diagnostics:

docker compose logs --tail=200 > unotusk-diagnostics.log
Copied to clipboard