llms.txt
# Vxero Neo
> Neo is a CLI tool for managing remote servers over SSH. It deploys Docker-based applications with zero-downtime updates, automatic SSL via Caddy, and shared database services — all without Kubernetes or complex orchestration.
## Installation
```bash
curl -fsSL https://get.vxero.dev/neo | sh
```
## Quick Start
```bash
neo init root@your-server-ip # Initialize a server (installs Docker + Caddy)
neo install ghost # Install Ghost blog with MySQL
neo deploy ./my-app # Deploy a Dockerfile-based project
```
## Architecture
- Runs locally on your machine, executes all operations on remote servers via SSH
- Uses Docker containers for apps and services, Caddy for reverse proxy + auto-SSL
- State stored at `/etc/neo/state.json` on each server
- Local config at `~/.neo/config.json` (multi-server support)
- Supports Ubuntu 24.04+ and Debian
## Commands
### Getting Started
- `neo` — Launch interactive TUI dashboard
- `neo init <user@host>` — Initialize a remote server (installs Docker, Caddy, creates neo network)
- `neo help` — Show grouped command reference
- `neo help --llm` — Machine-readable command reference (plain text, no colors)
### Applications
- `neo install [app]` — Install from template catalog (interactive picker if no app specified)
- `neo deploy [path]` — Build and deploy a Dockerfile-based project with blue-green deployment
- `neo list` — List all apps and shared services on the server
- `neo logs <app> [-f] [--tail N]` — Stream app container logs
- `neo logs <app> --worker <name>` — Stream a specific worker's logs
- `neo logs <app> --service` — Stream a shared service's logs
- `neo domain <app> <domain>` — Set or change the domain (auto-provisions SSL)
### Environment Variables
- `neo env <app>` — View env vars (secrets are masked)
- `neo env set <app> KEY=VALUE [KEY2=VALUE2...]` — Set env vars (auto-restarts app)
- `neo env unset <app> KEY` — Remove an env var
- `neo env import <app> .env` — Bulk import from .env file
### Shared Services
Shared services let multiple apps use a single database or cache, saving RAM on small VMs.
- `neo service create [type] [name]` — Create a shared service. Types: mysql, postgres, redis, mariadb
- `neo service list` — List shared services with linked apps
- `neo service link <service> <app>` — Link service to app. Creates a dedicated database + user, injects DATABASE_URL and DB_* env vars, restarts the app
- `neo service unlink <service> <app>` — Remove env vars from app (data is preserved)
- `neo service start <service>` — Start a stopped service
- `neo service stop <service>` — Stop a service (warns if apps are linked)
- `neo service restart <service>` — Restart a service
- `neo service remove <service>` — Remove a service (blocked if apps still linked)
- `neo service logs <service> [-f]` — Stream service logs
#### Shared Service Workflow Example
```bash
neo service create mysql # Create one shared MySQL instance
neo install ghost # When prompted, reuse existing MySQL
neo install wordpress # Same — both apps share one MySQL
neo service list # Shows: mysql → ghost, wordpress
neo service unlink mysql wordpress # Disconnect WordPress (data preserved)
```
#### Env Vars Injected by `neo service link`
For MySQL/MariaDB: DATABASE_URL, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD
For PostgreSQL: DATABASE_URL, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD
For Redis: REDIS_URL, REDIS_HOST, REDIS_PORT, REDIS_DB
### App Lifecycle
- `neo start <app>` — Start a stopped app (starts services first, then app, then workers)
- `neo stop <app>` — Stop a running app (stops workers first, then app, then services)
- `neo restart <app>` — Restart an app and its services
- `neo update <app>` — Pull latest image and replace container (preserves volumes and env)
- `neo remove <app>` — Remove app containers (data volumes are preserved on server)
### Data Management
- `neo backup <app>` — Backup app data volumes
- `neo restore <app> <file>` — Restore from a backup file
- `neo volumes` — List all Docker volumes on the server
### Server Management
- `neo servers` — List all configured servers
- `neo use <name>` — Switch the active server
- `neo ssh` — Open SSH session to the current server
- `neo --server <name> <command>` — Target a specific server for any command
### Updates
- `neo version` — Show current version, check for updates
- `neo upgrade` — Download and install the latest version
## Available App Templates
Install any of these with `neo install <name>`:
- `ghost` — Professional publishing platform (includes MySQL)
- `wordpress` — The world's most popular CMS (includes MySQL)
- `gitea` — Lightweight self-hosted Git service
- `n8n` — Workflow automation tool
- `plausible` — Privacy-friendly Google Analytics alternative (includes PostgreSQL, ClickHouse)
- `umami` — Simple, fast, privacy-focused web analytics
- `miniflux` — Minimalist RSS feed reader (includes PostgreSQL)
- `chatwoot` — Open-source customer engagement platform
- `vaultwarden` — Lightweight Bitwarden-compatible password manager
- `uptime-kuma` — Self-hosted monitoring tool
## Project Configuration (.neo.yml)
Optional file in project root for `neo deploy`:
```yaml
name: my-app # App name (default: directory name)
domain: app.example.com # Domain (default: prompted)
port: 8080 # Container port (default: from Dockerfile EXPOSE)
env_file: .env.production # Load env vars from file
compose_service: app # Which docker-compose service to use
env: # Default env vars
APP_ENV: production
LOG_LEVEL: info
workers: # Background worker processes
queue:
command: "python worker.py"
sidecars: # Sidecar containers
backup:
image: restic/restic
volumes:
content: /data
environments: # Named deployment targets
staging:
server: staging-box
domain: staging.example.com
```
## Docker Compose Auto-Detection
If your project has a `docker-compose.yml`, neo auto-detects:
- The main app service (prefers services with `build:` context)
- Environment variables and env_file references
- Container ports from `ports:` section
- Use `compose_service` in `.neo.yml` if auto-detection picks the wrong service
## Container Naming
- App containers: `app-<name>` (e.g., `app-ghost`)
- Shared services: `svc-<name>` (e.g., `svc-mysql`)
- Bundled services: `svc-<app>-<service>` (e.g., `svc-ghost-mysql`)
- Workers: `app-<app>-worker-<name>` (e.g., `app-ghost-worker-queue`)
- Sidecars: `svc-<app>-<sidecar>` (e.g., `svc-ghost-backup`)
- Reverse proxy: `neo-caddy`
- Network: `neo`
## Deployment Strategy
Neo uses blue-green deployment for zero downtime:
1. Builds image (locally or remotely)
2. Starts new container as `app-<name>-next`
3. Waits for health check (up to 30s)
4. Switches Caddy traffic to new container
5. Removes old container
6. Renames new container to `app-<name>`
