Klystrr Docs

What is Klystrr?

Klystrr is a deployment platform built for developers who want full control over their infrastructure. It bridges the gap between your Git repositories and your own VPS servers — letting you deploy, manage, and monitor applications through a clean dashboard, without writing shell scripts or configuring servers by hand.

Klystrr handles the operational layer of a deployment: SSH connection, repository cloning, dependency installation, process management via PM2, reverse proxy configuration via Nginx or Apache, and automatic SSL certificate provisioning. You focus on your code; Klystrr handles what happens after you push.

Who is it for?

• Independent developers who self-host one or more applications on a VPS and want a faster, more reliable deployment workflow
• Small technical teams that need a lightweight deployment layer without the complexity of a full CI/CD platform
• Developers moving away from managed hosting who want to keep costs down by running on their own servers without losing deployment ergonomics

Klystrr assumes you have technical familiarity with Linux servers, SSH, and Git. It is not a no-code tool.

What problem does it solve?

Deploying an application to a VPS typically involves:

• Manually SSHing into the server
• Pulling the latest code
• Installing dependencies
• Running a build
• Restarting the process
• Verifying Nginx is serving traffic
• Renewing SSL certificates

Doing this repeatedly — across multiple projects or servers — is error-prone and time-consuming. Klystrr automates every step and gives you a full audit trail of every deployment.

Required VPS information

• Host — the public IP address or hostname of your VPS
• SSH port — typically 22, unless you have configured a custom port
• SSH user — a Linux user with sufficient permissions
• Authentication — either a password or a private SSH key (key preferred)

SSH access requirements

The SSH user provided to Klystrr must be able to:

• Read and write to the deployment directory (default: /var/www/)
• Execute git, node, npm / pnpm / yarn
• Execute pm2 commands
• Reload Nginx or Apache (typically via sudo without a password prompt)

If you are not using root, configure passwordless sudo for the reload command:

# Add to /etc/sudoers.d/klystrr-deploy
your_user ALL=(ALL) NOPASSWD: /usr/sbin/nginx
# or for Apache:
your_user ALL=(ALL) NOPASSWD: /usr/sbin/apachectl

Pre-installation checklist:

git --version
node -v
npm -v
pm2 -v
nginx -v   # or apache2 -v
certbot --version

Supported web servers

Nginx is the default and recommended option. Klystrr automatically generates a server block that proxies traffic from your default domain to your application's local port.

Apache (apache2) is also supported. Klystrr generates an Apache VirtualHost configuration and reloads the service after each deployment. Ensure mod_proxy and mod_proxy_http are enabled:

sudo a2enmod proxy proxy_http

Required permissions

Security recommendations

• Use a dedicated deploy user instead of root. A user named deploy with scoped permissions limits the blast radius of a misconfiguration.
• Use SSH key authentication instead of passwords. Generate a dedicated key pair for Klystrr.
• Disable password authentication on SSH once your key is in place.
• Keep your server patched: apt update && apt upgrade regularly.
• Use a firewall: open only the ports your applications require (80, 443, 22).
• Rotate credentials periodically and update them in Klystrr's server settings.

# /etc/ssh/sshd_config
PasswordAuthentication no

Repository selection

Select a repository from the list of repositories accessible via your connected GitHub or GitLab account. Both public and private repositories are supported.

If a repository does not appear, check that your OAuth connection has the correct access scope, or that the repository belongs to an organization you have authorized.

Branch selection

Select the branch Klystrr should deploy from (e.g. main, production, release). Only the selected branch is used. If you enable auto-deployment, a webhook is registered on this branch only.

Install command

The command used to install your project's dependencies, run after the repository is cloned or pulled.

# Examples
npm install
pnpm install
yarn install
pip install -r requirements.txt

Leave empty if your project has no dependencies to install.

Build command

The command used to compile or bundle your application, run after the install step.

# Examples
npm run build
pnpm build
tsc

Leave empty if your application does not require a build step.

Start command

The command used to start your application. Klystrr wraps this with PM2 — do not include pm2 start yourself.

# Examples
node dist/main.js
npm run start:prod
python app.py
./bin/server

PM2 manages the process as a persistent background service. If the server restarts, PM2 will attempt to restart your application automatically (if pm2 save and pm2 startup are configured).

Environment variables

Go to your project's Environment tab to manage environment variables.

• Variables are encrypted at rest and never returned via the API after initial submission
• Values are masked in deployment logs
• Changes take effect on the next deployment — they are not hot-reloaded
• Use the bulk editor (KEY=VALUE format) or the individual field interface

NODE_ENV=production
PORT=3000
DATABASE_URL=postgres://user:pass@host:5432/db
JWT_SECRET=your-secret-here

Manual deployment

Go to your project page and click Deploy. Klystrr will immediately queue and start the deployment using the current project configuration and the latest commit on the configured branch.

Redeployment

Every deployment runs the full sequence from the beginning: pull latest code → install → build → restart PM2 → update proxy → verify SSL. There is no partial or incremental deployment.

Deployment status

A failed deployment does not automatically roll back. Depending on where the failure occurred, your previous application version may still be running via PM2.

Deployment logs

Real-time logs are accessible from the deployment detail view and include the exact commands Klystrr ran, stdout/stderr output, phase labels, timestamps, and exit status. Sensitive environment variable values are masked. Logs are retained for 90 days.

Deployment history

All past deployments are listed in the History tab of your project. Each entry shows the trigger type, triggered by, timestamp, duration, final status, and a link to the full log.

Rollback

Klystrr does not currently offer one-click rollback. If a deployment fails or introduces a regression, you can recover manually:

# SSH into your server
ssh user@your-server

# Go to the deployment directory
cd /var/www/your-project-name

# Reset to a specific previous commit
git log --oneline         # find the commit you want
git reset --hard <sha>

# Restart the application
pm2 restart your-project-name

Automated rollback with snapshot-based recovery is planned for a future release.

Default Klystrr domains

Every project automatically receives a default subdomain:

https://<project-name>.klystrr.app

The default domain is provisioned on your first successful deployment. No DNS configuration is required on your side. Domain names are derived from your project name and must be lowercase, alphanumeric, and may include hyphens.

Reverse proxy behavior

Klystrr configures a reverse proxy on your server to route traffic from your default domain to your application's local port. Your application does not need to handle TLS or port 443 directly.

Nginx example:

server {
    server_name my-api.klystrr.app;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Apache example:

<VirtualHost *:80>
    ServerName my-api.klystrr.app

    ProxyPreserveHost On
    ProxyPass / http://127.0.0.1:3000/
    ProxyPassReverse / http://127.0.0.1:3000/
</VirtualHost>

SSL generation

Klystrr provisions SSL certificates automatically using Let's Encrypt via Certbot during deployment. All HTTP traffic is permanently redirected to HTTPS. Certificates are valid for 90 days and auto-renewed by Certbot's own scheduled job on your server.

Verify the Certbot timer is active:

sudo systemctl status certbot.timer

Custom domains (planned)

Custom domain support (e.g. api.yourdomain.com) is planned for a future release. When available, it will allow you to point your own domain to a Klystrr project via a CNAME record and receive automatic SSL provisioning. This section will be updated when the feature is available.

GitHub connection

Go to Settings → Integrations → GitHub and click Connect GitHub. After OAuth authorization, Klystrr can list and access repositories you own or have been granted access to.

Revoke at any time: GitHub → Settings → Applications → Authorized OAuth Apps → Klystrr → Revoke.

GitLab connection

Go to Settings → Integrations → GitLab and click Connect GitLab. Both gitlab.com and self-hosted GitLab instances are supported (contact support for self-hosted configuration).

Revoke at any time: GitLab → Settings → Applications → find Klystrr → Revoke.

OAuth permissions explained

Klystrr requests the minimum necessary permissions. It does not request admin access, write access to your code, access to issues, PRs, secrets, or any data beyond what is needed to clone repositories and manage webhooks.

OAuth tokens are encrypted at rest and never exposed in the interface or API responses after initial authorization.