Requirements

• Linux/Unix (Debian, Ubuntu, etc.)
• Node.js 20+
• PM2 (auto-installed)
• Nginx (optional, for domains)
• Git

⚠️ Windows is not supported. Shyp is designed for Linux deployment.

Installation

npm install -g shyp

Before You Deploy

Before adding your first app, complete this checklist:

1. DNS Configuration

Point your domain to your server:

• Create an A record pointing yourdomain.com → your-server-ip
• Optional: Add a www subdomain if needed

2. Email Forwarding

Set up email forwarding for SSL certificate notifications:

• Create [email protected] forwarding to your real email
• This is used by Let's Encrypt for certificate expiry warnings

3. GitHub SSH Key

Ensure your server can pull from GitHub:

# Generate a deploy key (if you haven't already)
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_myapp -N ""

# Add the public key to your repo
cat ~/.ssh/id_ed25519_myapp.pub
# → GitHub repo → Settings → Deploy keys → Add deploy key

4. Webhook Secret (for auto-deploy)

Generate a shared secret for GitHub webhooks:

# Generate a random secret
openssl rand -hex 32

# Set it on your server
export SHYP_WEBHOOK_SECRET=your-generated-secret

Then configure the webhook in GitHub:

1. Go to your repo → Settings → Webhooks → Add webhook
2. Payload URL: http://your-server-ip:9000/
3. Content type: application/json
4. Secret: Your SHYP_WEBHOOK_SECRET
5. Events: Just the push event

Quick Start

# Initialize shyp (checks/installs prerequisites)
shyp init

# Add an app
shyp add my-app --repo [email protected]:you/my-app.git --domain my-app.com

# Apply configuration (generates nginx configs)
shyp sync

# Deploy
shyp deploy my-app

# Start webhook server for auto-deploys
shyp start

Why Shyp

Modern deployment tools are either too simplistic (manual PM2 + nginx) or too complex (Kubernetes, Docker Swarm).

Shyp is the sweet spot:

• File-based config - YAML files an AI can read and write
• No Docker required - Direct PM2 + Nginx, no container overhead
• Webhook auto-deploy - Push to GitHub, deploy automatically
• Multi-app management - One server, many apps, one tool

$ shyp status

Apps
──────────────────────────────────────────────────────────────────────
NAME                 STATUS       PORT     MEMORY     UPTIME       DOMAIN
my-app               ● online     3001     156MB      2d 4h        my-app.com
api-server           ● online     3002     89MB       5d 12h       api.example.com
landing-page         ● online     3003     45MB       12d 3h       example.com

Commands

| Command | Description | |---------|-------------| | shyp init | Initialize shyp, install prerequisites | | shyp status | Show status of all apps | | shyp deploy <name> | Deploy an app | | shyp add <name> | Add a new app configuration | | shyp sync | Sync configs, provision SSL certs, reload Nginx | | shyp ports | Show port allocations | | shyp logs <name> | View deployment logs | | shyp doctor | Check system health | | shyp start | Start webhook server |

Configuration

Shyp uses YAML files in /etc/shyp/:

/etc/shyp/
├── config.yaml          # Global configuration
├── apps/                # App configurations
│   ├── my-app.yaml
│   └── ...
├── engines/             # Engine configurations (modular apps)
└── state/               # Runtime state (ports, deployments)

App Configuration

name: my-app
repo: [email protected]:you/my-app.git
branch: main
path: /var/www/my-app
type: nextjs
domain: my-app.com

build:
  command: npm ci && npm run build

start:
  command: npm start

env:
  NODE_ENV: production

resources:
  memory: 512M
  instances: 1

Engine Configuration (Modular Apps)

For apps with multiple modules (like game engines):

type: engine
name: my-engine

server:
  repo: [email protected]:you/my-engine.git
  path: /var/www/my-engine
  pm2:
    name: my-engine
    memory: 2G

modules:
  game-frontend:
    domain: game.example.com
    port: 8000
    deploy:
      mode: script
      script: deploy.sh

Webhook Auto-Deploy

Set up GitHub webhooks to auto-deploy on push:

1. Go to your repo → Settings → Webhooks → Add webhook
2. Payload URL: http://your-server:9000/
3. Content type: application/json
4. Secret: Your SHYP_WEBHOOK_SECRET
5. Events: Just the push event

Set the secret on your server:

export SHYP_WEBHOOK_SECRET=your-secret-here

Start the webhook server:

shyp start

AI-Native Design

Shyp is designed for AI coding assistants like Claude Code:

• File-based - All config in readable YAML files
• Predictable paths - /etc/shyp/apps/*.yaml
• Idempotent - Run shyp sync safely anytime
• Clear output - Structured status for easy parsing

# AI can easily add a new app
cat > /etc/shyp/apps/new-project.yaml << 'EOF'
name: new-project
repo: [email protected]:you/new-project.git
path: /var/www/new-project
type: nextjs
domain: new-project.com
EOF

shyp sync
shyp deploy new-project

Links

• Website: shyp.now
• Documentation: shyp.now/docs
• GitHub: github.com/shypd/shyp
• Issues: github.com/shypd/shyp/issues
• npm: npmjs.com/package/shyp

License

MIT