Assistant Box 🤖

Turn your NVIDIA Jetson Orin Nano into a powerful, privacy-first AI assistant with GPU-accelerated local inference.

✨ Features

🧠 AI Models

Local Models: qwen3:4b and LFM2-1.2B-Tool-GGUF via Ollama
Cloud Models: Anthropic Claude and OpenAI GPT support
GPU Acceleration: CUDA-optimized inference on Jetson
Privacy-First: Run completely offline with local models

🔧 Core Capabilities

💬 Chat Interface: Modern web-based chat with streaming responses
📡 WiFi Management: Client mode network selection and management
🤖 MCP Tools: Extensible tool system with Linux command execution
🚀 Agent Launching: Autonomous task execution capabilities
📊 System Monitoring: Real-time health and performance metrics

🎯 Developer Experience

🔌 USB-C Plug & Play: Access via box.local hostname
🐳 JetsonContainers: Optimized Docker containers for Jetson devices
⚡ One-Click Setup: Automated installation and configuration
🔧 Extensible Architecture: Easy to add new MCP tools and features

🛠️ Hardware Requirements

Essential Hardware

NVIDIA Jetson Orin Nano Super Developer Kit (8GB recommended)
USB-C cable for host connection
MicroSD card (64GB UHS-1 or bigger recommended)

Storage Requirements

NVMe SSD (256GB minimum) - Required for running local models
MicroSD only - Sufficient for remote models only (requires internet connection)

💡 Storage Options:

With NVMe SSD: Run models locally for privacy and offline capability

MicroSD only: Use cloud models (requires internet and API keys)

Optional

External cooling for sustained performance
Ethernet cable for initial setup
Monitor and keyboard for direct access

🚀 Quick Start

Choose one of two setup methods:

Method 1: Pre-built Image (Recommended)

Download our custom image with Assistant Box pre-installed
Flash to microSD card using Etcher or similar
Insert microSD into Jetson Orin Nano and power on
Install NVMe SSD (required for local models) or configure for remote models only
Connect and use - everything is ready to go!

📋 Note: The pre-built image includes Assistant Box but still requires an NVMe SSD for local AI models. Without an SSD, you can only use remote models (requires internet and API keys).

🔑 Default Credentials: Username, hostname, and password are all box

⏱️ Boot Time: Allow 20-60 seconds for the system to fully boot and services to start

Method 2: Manual Setup

📋 Prerequisites:

For local models: Install NVMe SSD before proceeding

For remote models only: SSD is optional

1. Flash Official JetPack Image

First, download and flash the official NVIDIA JetPack image:

Download JetPack 6.x from the NVIDIA Jetson Orin Nano Developer Kit Getting Started Guide
Update firmware (required for JetPack 6.x compatibility)
Flash to microSD card using Etcher or similar

2. First Boot Setup

# Boot Jetson and complete Ubuntu setup
# Connect to internet via WiFi or Ethernet
sudo apt update && sudo apt upgrade -y

3. Install Assistant Box

# Clone repository
git clone https://github.com/assistant-ui/assistant-box.git
cd assistant-box

# Run automated installation
chmod +x scripts/*.sh
./scripts/install.sh

💾 Storage Setup:

With NVMe SSD: The installation script will automatically detect, format, and configure your SSD for local AI models and Docker storage

Without SSD: The script will configure the system for remote models only (requires internet and API keys)

4. Connect and Use

🔑 Default Credentials:

Username: box

Hostname: box (accessible as box.local)

Password: box

IP Address: 192.168.55.1

⏱️ Boot Time: Allow 20-60 seconds after powering on for the system to fully boot and all services to start

# Connect USB-C cable to host computer
# Open browser and navigate to:
http://box.local

# Or SSH directly:
ssh box@box.local 
# Password: box

# Alternative IP address:
ssh box@192.168.55.1

🎯 Usage Modes

Local Models (Requires NVMe SSD)

Privacy: Complete offline operation
Performance: GPU-accelerated inference
Models: qwen3:4b and LFM2-1.2B-Tool-GGUF
Storage: Models downloaded to SSD during setup

Remote Models (SSD Optional)

Internet: Requires stable connection
API Keys: Configure Anthropic Claude and/or OpenAI GPT
Storage: Minimal - only configuration and cache
Limitations: Dependent on internet and API availability

📁 Project Structure

assistant-box/
├── apps/
│   ├── host-ui/          # Next.js frontend
│   ├── device-server/    # FastAPI backend
│   └── mcp-hub/          # MCP tool server
├── packages/
│   ├── ui/               # Shared UI components
│   └── typescript-config/ # Shared TypeScript config
├── scripts/              # Setup and utility scripts
├── systemd/              # Systemd service files
└── docs/                 # Documentation

🎮 Usage Examples

Execute Linux Commands

// Via MCP Hub
const result = await mcpHub.callTool("run_linux_command", {
  command: "ls -la /home/box"
})

Launch Autonomous Agents

// Launch Claude Code SDK agent
const agent = await mcpHub.callTool("launch_agent", {
  task: "Analyze system performance and suggest optimizations",
  workingDirectory: "/home/box"
})

🔧 Configuration

System Credentials

The Assistant Box uses consistent credentials across all services:

Item	Value
Username	`box`
Password	`box`
Hostname	`box` (accessible as `box.local`)
IP Address	`192.168.55.1`

🔒 Security Note: Change the default password after initial setup for production use:
passwd box

Environment Variables

# Copy and edit configuration
cp env.example .env

# API Keys (optional for cloud models)
ANTHROPIC_API_KEY=your_key_here
OPENAI_API_KEY=your_key_here

# Service URLs
NEXT_PUBLIC_API_URL=http://box.local/api
NEXT_PUBLIC_MCP_HUB_URL=http://box.local:7000

Model Configuration

# docker-compose.yml
services:
  ollama:
    environment:
      OLLAMA_MODELS: /ssd/cache/ollama
      OLLAMA_NUM_PARALLEL: "1"
      OLLAMA_KEEP_ALIVE: "1min"

📚 Documentation

Document	Description
📖 Setup Guide	Complete installation from scratch
🏗️ Architecture	Technical system overview
🤝 Contributing	Development guidelines
🔧 API Reference	REST API documentation
🛠️ MCP Tools	Tool development guide

🚀 Development

Prerequisites

Node.js 18+ and Bun
Python 3.11+
Docker and Docker Compose

Setup Development Environment

# Install dependencies
bun install

# Start development servers
bun run dev

# Or start individually
cd apps/host-ui && bun run dev
cd apps/device-server && bun run dev
cd apps/mcp-hub && bun run dev

Adding New MCP Tools

// apps/mcp-hub/src/tools/my-tool.ts
export async function myTool(args: MyToolArgs) {
  // Tool implementation
  return {
    content: [{ type: 'text', text: 'Result' }]
  }
}

🧪 Testing

System Tests

# Run comprehensive system test
./scripts/test-system.sh

# Test individual components
bun run test:host-ui
bun run test:device-server
bun run test:mcp-hub

Health Monitoring

# Check system health
curl http://box.local/api/system-health

# Monitor services
sudo systemctl status host-ui device-server mcp-hub ollama

🔧 Troubleshooting

Common issues and their solutions using the diagnostic scripts in scripts/.

USB Gadget Networking Issues

Symptoms: Cannot access box.local or 192.168.55.1, USB device not detected by host

⏱️ First Boot? Allow 20-60 seconds for the system to fully boot before troubleshooting. Services need time to start.

Diagnostic Scripts

# Comprehensive USB gadget diagnostics
./scripts/diagnose-usb-gadget.sh

# Check USB gadget connection status
./scripts/check-usb-gadget-connection.sh

# Test USB gadget functionality (requires sudo)
sudo ./scripts/test-usb-gadget.sh

# For Jetson-specific USB diagnostics
./scripts/diagnose-jetson-usb.sh

Quick Fixes

# Clean up and reconfigure USB gadget
sudo ./scripts/cleanup-usb-gadget.sh
sudo ./scripts/setup-usb-gadget.sh

# Restart USB gadget service
sudo systemctl restart usb-gadget

# Bring up usb0 interface manually
sudo ip link set usb0 up
sudo ip addr add 192.168.55.1/24 dev usb0

Common Causes:

USB cable is power-only (not data-capable)
USB port doesn't support device/OTG mode
UDC (USB Device Controller) not properly bound
Network interface not configured

NVMe SSD Detection Issues

Symptoms: SSD not detected, /ssd not mounted, installation fails

Diagnostic Scripts

# Debug NVMe device detection
./scripts/debug-nvme.sh

# Test NVMe detection on Jetson
./scripts/test-nvme-detection.sh

# Test SSD setup functionality
./scripts/test-ssd-setup.sh

Quick Fixes

# Simple SSD configuration once ssd is connected
./scripts/setup-ssd-simple.sh

# Or specify device explicitly
sudo ./scripts/setup-ssd.sh /dev/nvme0n1

# Verify SSD and Docker setup
./scripts/verify-ssd-docker.sh

Common Causes:

NVMe SSD not properly seated in M.2 slot
Device permissions issues
SSD not formatted or partitioned correctly
Incorrect device path

Docker Storage Issues

Symptoms: Docker out of space, models won't download, containers failing

Diagnostic Scripts

# Verify Docker is using SSD storage
./scripts/verify-ssd-docker.sh

# Check Docker service status
sudo systemctl status docker
sudo docker info

Quick Fixes

# Migrate Docker to SSD (if not already done)
./scripts/migrate-docker-to-ssd.sh

# Free up space by removing unused containers/images
sudo docker system prune -a

Common Causes:

Docker still using /var/lib/docker on microSD
SSD not mounted before Docker starts
Docker daemon misconfigured

DNS/Network Conflicts

Symptoms: DNS resolution fails, port 53 conflicts, dnsmasq won't start

Diagnostic Scripts

# Check for DNS conflicts
sudo netstat -tlnp | grep :53
sudo systemctl status dnsmasq
sudo systemctl status systemd-resolved

Quick Fixes

# Fix DNS configuration and conflicts
sudo ./scripts/fix-dns.sh

# Verify configuration
resolvectl status

Common Causes:

Multiple DNS services running (systemd-resolved vs dnsmasq)
NetworkManager spawning its own dnsmasq
Port 53 already in use

USB Device Controller (UDC) Issues

Symptoms: UDC not available, binding failures, device tree errors

Diagnostic Scripts

# Diagnose UDC issues
./scripts/fix-udc-issues.sh

# Check for device tree USB configuration issues
./scripts/fix-jetson-dt-usb.sh

Quick Fixes

# Load USB gadget modules
sudo modprobe libcomposite

# Check available UDCs
ls /sys/class/udc

# Restart USB gadget service
sudo systemctl restart usb-gadget

Common Causes:

USB port not configured for device mode
libcomposite module not loaded
Device tree configuration issues
Hardware doesn't support USB gadget mode

System Health Issues

Symptoms: Services not running, API endpoints unresponsive, system slow

⏱️ Just Booted? Services can take 20-60 seconds to start after boot. Wait a minute before troubleshooting.

Diagnostic Scripts

# Comprehensive system test
./scripts/test-system.sh

# Check all service statuses
sudo systemctl status host-ui device-server mcp-hub ollama

Quick Fixes

# Restart all services
sudo systemctl restart host-ui device-server mcp-hub ollama

# Check service logs
sudo journalctl -u host-ui -n 50
sudo journalctl -u device-server -n 50
sudo journalctl -u mcp-hub -n 50

# Restart specific service
sudo systemctl restart mcp-hub
./scripts/restart-mcp-hub.sh

Common Causes:

Services crashed or failed to start
Memory pressure (add swap with ./scripts/setup-swap.sh)
Disk full (check with df -h)
Configuration errors

General Troubleshooting Tips

Check System Status

# Overall system health
./scripts/test-system.sh

# Service status
sudo systemctl status host-ui device-server mcp-hub ollama

# Check logs
sudo journalctl -xe

# Network status
ip addr show
ping 192.168.55.1

Reset Everything

# Clean slate - use with caution!
sudo ./scripts/cleanup-usb-gadget.sh
sudo systemctl stop host-ui device-server mcp-hub
sudo systemctl start host-ui device-server mcp-hub
sudo ./scripts/setup-usb-gadget.sh

Get Help

If issues persist after trying these steps:

Check Logs: sudo journalctl -u <service-name> -n 100
Run Diagnostics: Use the diagnostic scripts above
Report Issue: Include output from diagnostic scripts
Community Support: See Support section below

💡 Reminder: Default credentials are username: box, password: box, hostname: box.local

Script Reference

Script	Purpose	Requires Sudo
`diagnose-usb-gadget.sh`	Basic USB gadget diagnostics	No
`diagnose-jetson-usb.sh`	Jetson-specific USB diagnostics	Partial
`check-usb-gadget-connection.sh`	Check USB connection status	Partial
`test-usb-gadget.sh`	Comprehensive USB test	Yes
`cleanup-usb-gadget.sh`	Remove USB gadget config	Yes
`setup-usb-gadget.sh`	Configure USB gadget	Yes
`debug-nvme.sh`	Debug NVMe detection	No
`test-nvme-detection.sh`	Test NVMe device detection	Partial
`setup-ssd.sh`	Setup SSD storage	No*
`setup-ssd-simple.sh`	Simplified SSD setup	No*
`test-ssd-setup.sh`	Test SSD setup scripts	No
`verify-ssd-docker.sh`	Verify SSD and Docker	No*
`migrate-docker-to-ssd.sh`	Move Docker to SSD	No*
`fix-dns.sh`	Fix DNS conflicts	Yes
`fix-udc-issues.sh`	Fix UDC binding issues	Partial
`fix-jetson-dt-usb.sh`	Fix device tree USB issues	Partial
`setup-swap.sh`	Setup swap on NVMe	Yes
`test-system.sh`	Test entire system	No*
`restart-mcp-hub.sh`	Restart MCP Hub service	Yes

* Uses sudo internally when needed

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contribution

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

NVIDIA for the Jetson platform
Ollama for local LLM inference
shadcn/ui for beautiful UI components
FastAPI for the backend framework
Next.js for the frontend framework

📞 Support

Made with ❤️ by the Assistant Box Contributors

Name		Name	Last commit message	Last commit date
Latest commit History 37 Commits
apps		apps
docs		docs
packages		packages
scripts		scripts
systemd		systemd
.gitignore		.gitignore
.npmrc		.npmrc
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
SETUP_GUIDE.md		SETUP_GUIDE.md
WIFI_IMPLEMENTATION_SUMMARY.md		WIFI_IMPLEMENTATION_SUMMARY.md
bun.lock		bun.lock
docker-compose.yml		docker-compose.yml
env.example		env.example
package.json		package.json
turbo.json		turbo.json

Uh oh!

License

Uh oh!

assistant-ui/assistant-box

Folders and files

Latest commit

History

Repository files navigation

Assistant Box 🤖

✨ Features

🧠 AI Models

🔧 Core Capabilities

🎯 Developer Experience

🛠️ Hardware Requirements

Essential Hardware

Storage Requirements

Optional

🚀 Quick Start

Method 1: Pre-built Image (Recommended)

Method 2: Manual Setup

1. Flash Official JetPack Image

2. First Boot Setup

3. Install Assistant Box

4. Connect and Use

🎯 Usage Modes

Local Models (Requires NVMe SSD)

Remote Models (SSD Optional)

📁 Project Structure

🎮 Usage Examples

Execute Linux Commands

Launch Autonomous Agents

🔧 Configuration

System Credentials

Environment Variables

Model Configuration

📚 Documentation

🚀 Development

Prerequisites

Setup Development Environment

Adding New MCP Tools

🧪 Testing

System Tests

Health Monitoring

🔧 Troubleshooting

USB Gadget Networking Issues

Diagnostic Scripts

Quick Fixes

NVMe SSD Detection Issues

Diagnostic Scripts

Quick Fixes

Docker Storage Issues

Diagnostic Scripts

Quick Fixes

DNS/Network Conflicts

Diagnostic Scripts

Quick Fixes

USB Device Controller (UDC) Issues

Diagnostic Scripts

Quick Fixes

System Health Issues

Diagnostic Scripts

Quick Fixes

General Troubleshooting Tips

Check System Status

Reset Everything

Get Help

Script Reference

🤝 Contributing

Quick Contribution

📄 License

🙏 Acknowledgments

📞 Support

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Packages