localbox Documentation

Getting Started

Your localbox comes pre-configured with everything you need to start self-hosting. The initial setup takes less than 10 minutes and requires no technical expertise.

What's in the Box

• localbox device with custom case
• 30W USB-C power adapter
• Ethernet cable
• 256GB microSD card (pre-installed)
• Quick start guide

System Requirements

• Network: Ethernet or Wi-Fi connection
• Power: 30W USB-C power supply (included)
• Mobile Device: iOS 12+ or Android 8+
• Internet: Broadband connection recommended

Initial Setup

Setting up your localbox is designed to be as simple as possible. Follow these steps to get started:

Step 1: Power On

1. Connect the USB-C power adapter to your localbox
2. The device will boot automatically (takes ~2 minutes)
3. Look for the blue LED to indicate successful boot

Step 2: Connect to Setup Network

1. On first boot, localbox creates a Wi-Fi hotspot named "localbox-setup-XXXX"
2. Connect your mobile device to this network
3. The password is printed on the device label

Step 3: Configure with Mobile App

1. Download the localbox app from the App Store or Google Play
2. Open the app and tap "Setup New Device"
3. Follow the in-app instructions to configure Wi-Fi and basic settings
4. Choose your preferred domain name (yourname.localbox.io)

Step 4: Complete Setup

1. The device will restart and connect to your network
2. Initial application deployment takes 10-15 minutes
3. You'll receive a notification when setup is complete

Mobile App

The localbox mobile app is your central hub for managing your device, monitoring system health, and accessing your applications.

Dashboard

The main dashboard provides an overview of:

• System status and uptime
• Resource usage (CPU, memory, storage)
• Network connectivity
• Active applications
• Recent alerts and notifications

Application Management

Install and manage applications directly from the app:

• Browse available application stacks
• One-tap installation and configuration
• Monitor application health and logs
• Update applications when new versions are available

System Settings

Configure your localbox settings:

• Network configuration (Wi-Fi, Ethernet, VPN)
• Domain and SSL certificate management
• Backup schedules and destinations
• User accounts and permissions
• System updates and maintenance

Applications

localbox comes with pre-configured application stacks covering all major use cases. Each stack is carefully optimized and ready to use.

Privacy & Security Stack

• Headscale: Self-hosted VPN mesh network
• Pi-hole: Network-wide ad and tracker blocking
• Vaultwarden: Password manager compatible with Bitwarden
• Authentik: Identity provider with single sign-on

Media & Entertainment Stack

• Plex/Jellyfin: Media server for your personal collection
• *arr Stack: Automated media discovery and management
• Calibre: E-book library management

Productivity Stack

• Nextcloud: File sync, collaboration, and productivity suite
• Immich: Photo and video backup with AI features
• AFFiNE: Modern knowledge base and note-taking
• Stirling PDF: PDF manipulation and processing tools

Installing Applications

Applications can be installed through the mobile app or web interface:

1. Open the localbox app
2. Navigate to "Applications" → "Browse Stacks"
3. Select the stack you want to install
4. Configure any necessary settings
5. Tap "Install" and wait for deployment to complete

# Advanced users can also use the command line
kubectl apply -f /opt/localbox/stacks/media-stack.yaml

Networking

localbox provides flexible networking options to suit your environment and security requirements.

Local Network Access

By default, localbox is accessible on your local network via:

• mDNS: localbox.local
• IP Address: Assigned by your router's DHCP
• Custom Domain: Configure a local domain if desired

External Access

For remote access, localbox offers several secure options:

• DDNS Service: yourname.localbox.io subdomain
• VPN Access: Through Headscale mesh network
• Cloudflare Tunnel: Secure tunnel without port forwarding

Port Configuration

If using port forwarding, these are the standard ports:

• 80: HTTP (redirects to HTTPS)
• 443: HTTPS (Traefik ingress)
• 8080: localbox management interface

Storage & Backups

localbox uses Longhorn for distributed storage with built-in backup capabilities.

Storage Overview

• Primary Storage: 256GB microSD card
• Expansion: USB 3.0 external storage
• Network Storage: NFS, SMB/CIFS support
• Backup Destinations: S3-compatible, SSH, local

Adding External Storage

1. Connect USB storage device to localbox
2. Open the mobile app → Storage
3. Tap "Add Storage Volume"
4. Select the connected device and configure
5. Choose which applications should use the new storage

Backup Configuration

Set up automated backups through the mobile app:

1. Navigate to Settings → Backups
2. Add backup destination (cloud storage, NAS, etc.)
3. Configure backup schedule and retention
4. Select which data to include in backups
5. Test the backup configuration

# Manual backup creation
kubectl exec -n longhorn-system deployment/longhorn-manager -- \
  longhorn backup create --volume-name pvc-data-volume

Security

localbox implements multiple layers of security to protect your data and applications.

Built-in Security Features

• Encrypted Storage: All data encrypted at rest using Longhorn
• TLS Certificates: Automatic Let's Encrypt certificates
• Network Policies: Kubernetes network segmentation
• RBAC: Role-based access control for all services
• Regular Updates: Automatic security patches

Authentication

localbox supports multiple authentication methods:

• Local Accounts: Built-in user management
• SSO Integration: Via Authentik identity provider
• LDAP/Active Directory: Enterprise directory integration
• 2FA Support: TOTP and hardware keys

Network Security

• Firewall: Built-in iptables rules
• VPN Access: Headscale mesh network
• Intrusion Detection: Log monitoring and alerting
• DDoS Protection: Rate limiting and traffic analysis

Multi-Node Setup

Connect multiple localbox devices for increased performance, redundancy, and storage capacity.

Adding a Second Node

1. Set up the second localbox following normal setup procedure
2. During setup, the app will detect existing nodes
3. Choose "Join Existing Cluster"
4. Authenticate with your admin credentials
5. Wait for the new node to sync with the cluster

Cluster Benefits

• Load Distribution: Workloads spread across nodes
• High Availability: Service continuity if one node fails
• Storage Replication: Data replicated across nodes
• Rolling Updates: Zero-downtime application updates

Network Requirements

• All nodes must be on the same local network
• Gigabit Ethernet recommended for storage replication
• Consider a managed switch for dedicated cluster traffic

Troubleshooting

Common issues and their solutions.

Device Won't Boot

• Check power connection and LED status
• Verify microSD card is properly seated
• Try a different power adapter (30W minimum)
• Contact support if LED shows error pattern

Can't Connect to Setup Network

• Wait 3-5 minutes after powering on
• Check for "localbox-setup-XXXX" in Wi-Fi networks
• Ensure mobile device supports 2.4GHz Wi-Fi
• Reset device by holding reset button for 10 seconds

Applications Not Loading

• Check system status in mobile app
• Verify internet connectivity
• Allow 15 minutes for initial deployment
• Check container logs in the monitoring interface

Performance Issues

• Monitor resource usage in dashboard
• Check for thermal throttling
• Consider adding external storage for heavy workloads
• Review application resource limits

Getting Help

If you need additional support:

• Documentation: This guide and online docs
• Community: Discord server and Reddit community
• Support Tickets: Email support for technical issues
• Remote Assistance: Scheduled help sessions available

API Reference

For advanced users and developers, localbox provides REST APIs for automation and integration.

Authentication

API access requires authentication via JWT tokens:

curl -X POST https://your-localbox.io/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "your-password"}'

System Information

GET /api/v1/system/status
GET /api/v1/system/resources
GET /api/v1/system/logs

Application Management

GET /api/v1/applications
POST /api/v1/applications/{stack}/install
DELETE /api/v1/applications/{app}/uninstall
PUT /api/v1/applications/{app}/update

Storage Management

GET /api/v1/storage/volumes
POST /api/v1/storage/volumes
GET /api/v1/backups
POST /api/v1/backups/create