@nervur-ai/homeserver

CLI tool to quickly spin up a Continuwuity Matrix homeserver optimized for nervur-brain usage.

Quick Start

npx @nervur-ai/homeserver init

This single command will:

• ✅ Verify Docker is installed and running
• ✅ Guide you through an interactive setup wizard
• ✅ Generate all necessary configuration files
• ✅ Pull Docker images and start your homeserver
• ✅ Verify everything is working

Requirements

• Docker - Install Docker
• Node.js >= 18.0.0

Installation Methods

Option 1: Direct npx usage (recommended)

No installation needed! Just run:

npx @nervur-ai/homeserver init

Option 2: Global installation

npm install -g @nervur-ai/homeserver
nervur-homeserver init

Option 3: Local project installation

npm install @nervur-ai/homeserver
npx nervur-homeserver init

Commands

init

Initialize a new Continuwuity homeserver with interactive setup wizard.

npx @nervur-ai/homeserver init

What it does:

1. Runs pre-flight checks (Docker, ports, permissions)
2. Asks for your server name (domain)
3. Lets you choose between Cloudflare Tunnel or Static IP
4. Generates docker-compose.yml, config files, and documentation
5. Pulls Docker images
6. Starts the homeserver
7. Verifies it's running

status

Check if your homeserver is running and healthy.

npx @nervur-ai/homeserver status

logs

View homeserver logs.

# View last 50 lines
npx @nervur-ai/homeserver logs

# Follow logs in real-time
npx @nervur-ai/homeserver logs --follow

start

Start a stopped homeserver.

npx @nervur-ai/homeserver start

stop

Stop the running homeserver.

npx @nervur-ai/homeserver stop

restart

Restart the homeserver (useful after config changes).

npx @nervur-ai/homeserver restart

Setup Options

Cloudflare Tunnel (Recommended)

• ✅ No static IP required
• ✅ Works behind NAT/firewall
• ✅ Free SSL certificate
• ✅ DDoS protection

Steps:

1. Run npx @nervur-ai/homeserver init
2. Select "Cloudflare Tunnel"
3. Get a tunnel token from Cloudflare Zero Trust
4. Configure the public hostname in Cloudflare dashboard

Static IP + DNS

• Requires control over your domain's DNS
• Requires a static IP address
• Ports 8008 and 8448 must be accessible

Steps:

1. Run npx @nervur-ai/homeserver init
2. Select "Static IP + DNS"
3. Configure DNS records as instructed
4. Ensure firewall allows ports 8008 and 8448

Creating Your First User

After setup, create an admin user:

docker exec -it continuwuity register_new_matrix_user -c /data/homeserver.yaml http://localhost:8008

Follow the prompts to set:

• Username
• Password
• Admin status (yes)

Next Steps

1. Create an admin user (see above)
2. Install nervur-brain and connect it to your homeserver
3. Start using Matrix with your new homeserver!

Configuration

All configuration files are generated in your current directory:

• docker-compose.yml - Docker service definitions
• continuwuity-config.yaml - Homeserver configuration
• .env - Environment variables
• HOMESERVER-README.md - Setup-specific documentation

To modify configuration:

1. Edit continuwuity-config.yaml
2. Run npx @nervur-ai/homeserver restart

Data Storage

All homeserver data is stored in the data directory you specified during setup (default: ./nervur-homeserver-data):

• Database (homeserver.db)
• Media files (media/)
• Log files

Important: Back up this directory regularly!

Troubleshooting

Homeserver won't start

# Check Docker is running
docker info

# View logs
npx @nervur-ai/homeserver logs

# Check status
npx @nervur-ai/homeserver status

Ports already in use

If ports 8008 or 8448 are already in use, stop the conflicting service:

# Find what's using the port
lsof -i :8008
lsof -i :8448

Can't connect externally

For Cloudflare Tunnel:

• Verify tunnel is active in Cloudflare dashboard
• Check public hostname points to http://continuwuity:8008

For Static IP:

• Verify DNS records are configured correctly
• Check firewall allows ports 8008 and 8448
• Test with: curl http://your-ip:8008/_matrix/client/versions

Permission denied

If you get permission errors on the data directory:

# Option 1: Choose a different directory
npx @nervur-ai/homeserver init

# Option 2: Fix permissions
sudo chown -R $USER:$USER ./nervur-homeserver-data

Nervur-Optimized Defaults

This tool configures Continuwuity with settings optimized for nervur-brain:

• Database: SQLite (leveldb fallback)
• Registration: Disabled by default (use shared secret)
• Media uploads: 50MB max
• Metrics: Disabled
• URL previews: Disabled
• Federation: Enabled with whitelist support

Development

# Clone the repository
git clone https://github.com/nervur-ai/homeserver.git
cd homeserver

# Install dependencies
npm install

# Link for local development
npm link

# Test locally
nervur-homeserver init

License

MIT License - See LICENSE file for details.

Links

• GitHub Repository
• nervur-brain
• Continuwuity
• Matrix Protocol

Support

For issues and questions:

• GitHub Issues
• Matrix Community