Documentation
Welcome to shebang.run documentation. Learn how to host, share, and execute scripts with versioning and encryption.
For developers: See the API Reference for complete REST API documentation.
Quick Start
1. Create an Account
Sign up at shebang.run/register
2. Create Your First Script
Go to your Dashboard and click "New Script"
echo "Hello from shebang.run!"
3. Use Your Script
Usage
Retrieve Scripts
Get Metadata
Returns JSON with version, checksum, size, and timestamps
Verify Signature
Check if script is signed and verified
CLI Tool
Installation
Quick Start
# Login and generate API credentials shebang login # List your scripts shebang list # List community scripts shebang list -c # Search scripts shebang search "deploy" # Get a script shebang get myscript # Run a script shebang run myscript # Upload a script shebang put -n myscript -v public -f script.sh
Key Management
# List keys shebang list-keys # Create new keypair shebang create-key -O mykey.pem # Delete key shebang delete-key keyname
Secrets Management
# List secrets shebang list-secrets # Get secret value shebang get-secret AWS_KEY # Get in bash format shebang get-secret AWS_KEY -f env # Create/update secret shebang put-secret AWS_KEY -v "AKIA..." echo "value" | shebang put-secret KEY -s # Delete secret shebang delete-secret AWS_KEY # View audit log shebang audit-secret AWS_KEY
Script Sharing
# List who has access shebang list-shares myscript # Share with users shebang share myscript -u alice -u bob # Enable link sharing shebang share myscript -l # Remove access shebang share myscript -u alice -r shebang share myscript -l -r # Hide shared scripts from list shebang list -i
Secret Substitution
# Scripts can reference secrets
#!/bin/bash
ssh ${SECRET:Host}
# Get with substitution
shebang get myscript -s
# Run always substitutes
shebang run myscript
Docker Usage
# Use CLI via Docker docker run -it --rm -v ~/.shebangrc:/root/.shebangrc \ docker.twillcode.com/skibare87/shebangrun:cli shebang list # Create alias alias shebang='docker run -it --rm -v ~/.shebangrc:/root/.shebangrc docker.twillcode.com/skibare87/shebangrun:cli'
Python Library
Installation
Basic Usage
from shebangrun import run
# Fetch a script
content = run(username="user", script="myscript")
# Execute with confirmation
run(username="user", script="myscript", eval=True)
# Execute without confirmation (use with caution!)
run(username="user", script="myscript", eval=True, accept=True)
# Decrypt encrypted script
content = run(
username="user",
script="private",
key=open("private.pem").read()
)
Features
📦 Versioning
Auto-incrementing versions with immutable history. Access any version with @v1, @v2, etc.
🔐 Encryption
End-to-end encryption with RSA-4096 and ChaCha20-Poly1305. Your private keys never leave your device.
🏷️ Tags
Tag versions as @latest, @dev, or @beta for easy reference and deployment workflows.
👥 Sharing
Public, unlisted, or private scripts. Share private scripts with revocable tokens.
🔑 Key Management
Generate or import RSA keypairs for signing and encrypting your scripts.
⚡ Rate Limiting
Configurable per-user rate limits to prevent abuse while ensuring availability.
API Reference
Public Endpoints
GET /{username}/{script}[@tag]
Retrieve script content
GET /{username}/{script}/meta
Get script metadata (JSON)
GET /{username}/{script}/verify
Verify script signature
Authentication
POST /api/auth/register
Register new user
POST /api/auth/login
Login and get JWT token
GET /api/auth/oauth/{provider}
OAuth login (github, google)
Script Management (Authenticated)
GET /api/scripts
List your scripts
POST /api/scripts
Create new script
PUT /api/scripts/{id}
Update script (creates new version)
DELETE /api/scripts/{id}
Delete script
Encryption
How It Works
- Generate or import an RSA-4096 keypair
- Create a private script and select your key
- Content is encrypted with ChaCha20-Poly1305
- Encryption key is wrapped with your RSA public key
- Only you can decrypt with your private key
⚠️ Important: Your private key is never stored on our servers. Download it immediately after generation and store it securely.
Decryption
Use the Python library to decrypt:
from shebangrun import run
content = run(
username="user",
script="encrypted-script",
key=open("private.pem").read()
)
print(content)
Self-Hosting
Docker Deployment
git clone https://github.com/skibare87/shebangrun.git cd shebangrun # Configure environment export JWT_SECRET="your-secret-key" export GITHUB_CLIENT_ID="your-github-id" export GITHUB_CLIENT_SECRET="your-github-secret" # Start the stack docker-compose up -d
See GitHub repository for complete deployment instructions.
Examples
Deployment Script
#!/bin/bash # Save as: deploy.sh git pull origin main docker-compose down docker-compose up -d --build echo "Deployment complete!"
Use: curl https://shebang.run/user/deploy | sh
Python Automation
#!/usr/bin/env python3
import os
import sys
print(f"Running on: {sys.platform}")
print(f"Python version: {sys.version}")
# Your automation code here
Execute: python3 -c "from shebangrun import run; run('user', 'script', eval=True, accept=True)"
Security
Best Practices
- Always review scripts before executing with
eval=True - Use
accept=Falseto see scripts before execution - Store private keys securely, never commit to version control
- Use environment variables for tokens and credentials
- Verify script checksums when security is critical
- Use encryption for sensitive scripts
Algorithms
- Password Hashing: bcrypt
- Authentication: JWT with HS256
- Key Generation: RSA-4096
- Key Wrapping: RSA-OAEP with SHA-256
- Content Encryption: XChaCha20-Poly1305
- Checksums: SHA-256