AIXCL

A self-hosted, local-first AI development platform with enterprise security.

Run Large Language Models locally with HashiCorp Vault, GPG-signed commits, and rootless Podman.

Mandatory Minimum Requirements

Quick Start

Step 1: Install Prerequisites

Container Engine (choose one):

# Podman (recommended -- primary engine)
sudo apt-get update
sudo apt-get install -y podman podman-compose

# Docker (fallback -- optional)
sudo apt-get install -y docker.io docker-compose-v2

Required tools:

sudo apt-get install -y git gnupg2 gh

Verify:

podman --version    # Should show 4.9+
gpg --version       # Should show 2.2+
gh --version        # Should show 2.x+

Contributors only -- CI tools:

# yamllint (available via apt)
sudo apt-get install -y yamllint

# ShellCheck 0.11.0+ (apt package 0.9.0 is too old -- use GitHub releases)
curl -sSL https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.linux.x86_64.tar.xz | tar -xJ -C /tmp
sudo cp /tmp/shellcheck-v0.11.0/shellcheck /usr/local/bin/shellcheck

VM users (QEMU/SLIRP networking): If image pulls fail mid-download, add the following to /etc/docker/daemon.json to work around MTU limitations:

{"dns": ["8.8.8.8", "8.8.4.4"], "mtu": 1400, "max-concurrent-downloads": 1}

Then restart Docker: sudo systemctl restart docker

Step 2: Clone and Initialise

git clone https://github.com/xencon/aixcl.git
cd aixcl
./aixcl stack init

stack init automatically:

• Detects and configures Podman (rootless) or Docker
• Adds docker=podman alias and DOCKER_HOST to ~/.bashrc
• Creates .env from config/.env.example
• Creates opencode.json from config/opencode.json.example
• Initialises all external Docker/Podman volumes
• Prompts for admin username and email

After init, reload your shell:

source ~/.bashrc

Step 3: Start the Stack

./aixcl stack start --profile sys

This pulls images, starts all services, initialises Vault, and generates bootstrap credentials. Allow 3-5 minutes for full startup on first run.

Note: Use --profile bld for a monitoring-only stack (no WebUI). Use --profile sys for the full stack with WebUI and pgAdmin.

Check status:

./aixcl stack status

Important: Vault auto-seals whenever its container restarts (e.g. after ./aixcl stack stop or host reboot). If services fail to start, unseal Vault first:

# Unseal Vault after every stack restart
./aixcl vault unseal

# Wait 30 seconds for bootstrap agents, then verify
./aixcl stack status

Step 4: View Credentials

./aixcl vault credentials

Step 5: Test Inference (Hello World)

./aixcl models add qwen2.5-coder:0.5b

Test via API:

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen2.5-coder:0.5b", "messages": [{"role": "user", "content": "Hello, are you working?"}]}'

Access Points

Get current service credentials:

./aixcl vault credentials

Mandatory Workflow

Every commit must be GPG-signed:

# Configure Git (one-time)
git config --global commit.gpgsign true

# Commits are automatically signed
vim some-file.txt
git add some-file.txt
git commit -m "feat: add new feature"  # Automatically signed

# Verify signature
git log --show-signature -1

Common Commands

Security Features (Mandatory)

The following are not optional and cannot be disabled:

• [x] Podman rootless - No privileged containers
• [x] GPG-signed commits - All commits to main must be signed (CODEOWNERS only)
• [x] HashiCorp Vault - Dynamic secrets with automatic rotation
• [x] PostgreSQL SSL - Encrypted database connections
• [x] Host firewall - Network isolation at host level

See SECURITY.md for architecture details.

Troubleshooting

"GPG signing failed"

# Re-run setup
./scripts/utils/setup-gpg.sh

# Verify key exists
gpg --list-secret-keys --keyid-format LONG

"Podman not running rootless"

# Check user namespaces
sysctl kernel.unprivileged_userns_clone

# Should return 1, if not:
echo 'kernel.unprivileged_userns_clone=1' | sudo tee /etc/sysctl.d/99-userns.conf
sudo sysctl --system

"Podman rootless setup failed"

If ./scripts/utils/setup-podman-rootless.sh fails, check manually:

# Verify subordinate UIDs/GIDs are configured
grep "^$(whoami):" /etc/subuid
grep "^$(whoami):" /etc/subgid

# If missing, add them manually (requires sudo)
echo "$(whoami):100000:65536" | sudo tee -a /etc/subuid
echo "$(whoami):100000:65536" | sudo tee -a /etc/subgid

# Start the podman socket manually
systemctl --user start podman.socket

# Re-run the setup script
./scripts/utils/setup-podman-rootless.sh

"Vault not initializing"

# Check Vault status
podman logs vault | tail -20

# Ensure Vault is healthy before init
./aixcl stack status

"Services won't start"

# Check for port conflicts
sudo lsof -i :11434  # Ollama
sudo lsof -i :8080   # Open WebUI
sudo lsof -i :8200   # Vault

# Soft reset -- removes volumes and state, keeps images for fast restart
./aixcl utils prune
./aixcl stack init
./aixcl stack start --profile sys

# Full wipe -- removes everything including images (slow rebuild)
./aixcl utils prune --all
./aixcl stack init
./aixcl stack start --profile sys

Deploying Apps

AIXCL supports bringing your own applications (BYO) via the app framework. Install from a Git URL, scaffold a new app, or manage existing apps:

# Install an app from a Git repository
./aixcl app install https://github.com/example/my-app.git

# Scaffold a new app skeleton
./aixcl app scaffold my-app

# List, start, stop, or remove apps
./aixcl app list
./aixcl app start my-app
./aixcl app stop my-app
./aixcl app remove my-app

See docs/user/apps.md for the complete app guide.

1. Add more models: ./aixcl models add qwen2.5-coder:1.5b
2. Customize: Edit .env for your environment
3. Learn: See docs/ for detailed guides
4. Contribute: Read CONTRIBUTING.md

License

Apache License 2.0