# AIOStreams Self-Hosting Guide (100% Free - No Credit Card Required) 1. 1.
This guide will help you self-host AIOStreams using completely free services: **Neon (database)** and **HuggingFace (web service)**. 1. 1.
## Prerequisites 1. 1.
- A GitHub account (to sign up for services)
- 10-15 minutes of your time
## Step 1: Create Your PostgreSQL Database on Neon 1. 1.
### 1.1 Sign Up for Neon 1.
1. Go to **https://neon.tech** 1.
2. Click "Sign Up" and use your GitHub account (no credit card needed) 1. 1.
### 1.2 Create a New Project 1.
1. Once logged in, click "**Create a project**" 1.
2. Give it any name (e.g., "aiostreams-db") 1.
3. Select a region closest to you 1.
4. Click "**Creat…
# AIOStreams Self-Hosting Guide (100% Free - No Credit Card Required) 1. 1.
This guide will help you self-host AIOStreams using completely free services: **Neon (database)** and **HuggingFace (web service)**. 1. 1.
## Prerequisites 1. 1.
- A GitHub account (to sign up for services)
- 10-15 minutes of your time
## Step 1: Create Your PostgreSQL Database on Neon 1. 1.
### 1.1 Sign Up for Neon 1.
1. Go to **https://neon.tech** 1.
2. Click "Sign Up" and use your GitHub account (no credit card needed) 1. 1.
### 1.2 Create a New Project 1.
1. Once logged in, click "**Create a project**" 1.
2. Give it any name (e.g., "aiostreams-db") 1.
3. Select a region closest to you 1.
4. Click "**Create project**" 1. 1.
### 1.3 Get Your Database URI 1.
1. In your project dashboard, click the "**Connection string**" or "**Connect**" button 1.
2. You’ll see a URI that looks like: 1.
``` 1. 1.
``` 1.
3. **IMPORTANT:** Remove `ql` from `postgresql://` so it becomes `postgres://` 1.
4. **Copy this modified URI** - you’ll need it later 1. 1.
✅ **Correct format:** 1.
``` 1. 1.
``` 1. 1.
### 1.4 Adjust Autoscaling (Optional but Recommended) 1.
1. In your Neon project, go to "**Settings**" 1.
2. Find "**Compute**" or "**Autoscaling**" settings 1.
3. Set vCPU usage to between **0.25 and 0.5 vCPU** 1.
4. This helps stay within free tier limits 1. 1.
## Step 2: Prepare Your Configuration Values 1. 1.
Before deploying, you need to prepare these values. **Write them down in a notepad** - you’ll need them in Step 3. 1. 1.
### 2.1 Create ADDON_PASSWORD 1.
- **Simply choose a password** you want to use (like creating any password)
- Examples: `MyStreams2024!` or `SuperSecret123` or `AIO_Pass_456`
- This will be used to access your AIOStreams addon in Stremio
### 2.2 Generate SECRET_KEY 1.
You need a random 64-character hexadecimal key. Choose one method: 1. 1.
**Option A: Use Online Generator (Easiest)** 1.
1. Go to **https://www.grc.com/passwords.htm** 1.
2. Scroll to "**63 random hexadecimal characters**" (middle of the page) 1.
3. Copy the generated key 1. 1.
**Option B: Use PowerShell (Windows)** 1.
1. Open PowerShell 1.
2. Run this command: 1.
```powershell 1.
-join ((0..31) | ForEach-Object { ‘{0:x2}’ -f (Get-Random -Minimum 0 -Maximum 255) }) 1.
``` 1.
3. Copy the output 1. 1.
**Option C: Use Terminal (Mac/Linux)** 1.
1. Open Terminal 1.
2. Run this command: 1.
```bash 1.
openssl rand -hex 32 1.
``` 1.
3. Copy the output 1. 1.
### 2.3 Prepare BASE_URL 1.
- You’ll need your HuggingFace Space URL
- Format: `https://YOUR-USERNAME-SPACE-NAME.hf.space`
- Example: `https://john123-aiostreams.hf.space`
- **Don’t worry if you don’t know it yet** - we’ll come back to this in Step 3.4
📝 **Summary - Save these values in a notepad:** 1.
``` 1.
DATABASE_URI: (from Step 1.3) 1.
ADDON_PASSWORD: (your chosen password) 1.
SECRET_KEY: (64-character hex string) 1.
BASE_URL: (we’ll fill this in Step 3.4) 1.
``` 1. 1.
## Step 3: Deploy AIOStreams on HuggingFace 1. 1.
### 3.1 Sign Up for HuggingFace 1.
1. Go to **https://huggingface.co** 1.
2. Click "Sign Up" and create a free account (no credit card needed) 1. 1.
### 3.2 Create a New Space 1.
1. Click on your profile icon → "**New Space**" 1.
2. Fill in the details: 1.
- **Name:** `aiostreams` (or any name you like)
- **License:** Choose any (e.g., "MIT")
- **Select the Space SDK:** Choose "**Docker**"
- **Docker template:** Select "**Blank**"
- **Space hardware:** Select "**CPU basic - Free**"
- **Visibility:** Set to "**Public**"
3. Click "**Create Space**" 1. 1.
### 3.3 Create the Dockerfile 1.
1. In your new Space, you’ll see a file editor 1.
2. Click "**Files**" tab → "**Add file**" → "**Create a new file**" 1.
3. Name the file: `Dockerfile` (exactly as written, capital D) 1.
4. Choose which version to use and paste the content: 1. 1.
#### **Basic Version (Default - 15 addons max)** 1.
```dockerfile 1.
FROM ghcr.io/viren070/aiostreams:latest 1. 1.
ENV PORT=7860 1.
ENV EASYNEWS_PLUS_PLUS_URL=https://en.pantelx.com/ 1. 1.
EXPOSE 7860 1. 1.
CMD ["uvicorn", "main:app", "–host", "0.0.0.0", "–port", "7860"] 1.
``` 1. 1.
#### **Extended Version (More addons + Regex support) - Recommended** 1.
```dockerfile 1.
FROM ghcr.io/viren070/aiostreams:latest 1. 1.
ENV PORT=7860 1.
ENV MAX_ADDONS=50 1.
ENV REGEX_FILTER_ACCESS=all 1.
ENV EASYNEWS_PLUS_PLUS_URL=https://en.pantelx.com/ 1. 1.
EXPOSE 7860 1. 1.
CMD ["uvicorn", "main:app", "–host", "0.0.0.0", "–port", "7860"] 1.
``` 1. 1.
**Configuration Notes:** 1.
- `MAX_ADDONS=50` - Change `50` to any number you want (allows more than the default 15 addons)
- `REGEX_FILTER_ACCESS=all` - Enables advanced regex filtering capabilities
- `EASYNEWS_PLUS_PLUS_URL=https://en.pantelx.com/` - Fixes "Failed to fetch manifest" error for Easynews++ addon on HuggingFace
- Use the **Extended Version** if you need more than 15 addons or want regex features (recommended for most users)
- Use the **Basic Version** if you’re just starting out (you can always update later)
5. Click "**Commit new file to main**" 1. 1.
### 3.4 Get Your Space URL (Important!) 1.
Before adding secrets, you need to know your Space’s URL: 1. 1.
1. Look at your browser’s address bar - it will show: 1.
``` 1.
https://huggingface.co/spaces/YOUR-USERNAME/aiostreams 1.
``` 1.
2. Your actual Space URL (BASE_URL) will be: 1.
``` 1.
https://YOUR-USERNAME-aiostreams.hf.space 1.
``` 1.
3. **Example:** If the browser shows `https://huggingface.co/spaces/john123/aiostreams`, your BASE_URL is: 1.
``` 1.
https://john123-aiostreams.hf.space 1.
``` 1.
4. **Write this down** - you’ll need it in the next step! 1. 1.
### 3.5 Add Environment Variables (Secrets) 1.
1. Click on the "**Settings**" tab in your Space 1.
2. Scroll down to "**Variables and secrets**" section 1.
3. Click "**New secret**" and add these **FOUR secrets** one by one: 1. 1.
**Secret 1:** 1.
- Name: `DATABASE_URI`
- Value: Your Neon database URI from Step 1.3 (starts with `postgres://`)
**Secret 2:** 1.
- Name: `ADDON_PASSWORD`
- Value: Your chosen password from Step 2.1
**Secret 3:** 1.
- Name: `SECRET_KEY`
- Value: Your 64-character hex key from Step 2.2
**Secret 4:** 1.
- Name: `BASE_URL`
- Value: Your HuggingFace Space URL from Step 3.4 (format: `https://username-spacename.hf.space`)
4. Click "**Save**" after adding each secret 1. 1.
### 3.6 Wait for Deployment 1.
1. Go back to your Space’s main page (click the "**App**" tab) 1.
2. HuggingFace will automatically start building your Space 1.
3. Wait 2-5 minutes for the build to complete 1.
4. You’ll see "**Running**" status when it’s ready 1.
5. The app should display without errors 1. 1.
## Step 4: Keep Your Instance Alive (Optional but Recommended) 1. 1.
HuggingFace shuts down your Space after **48 hours of inactivity**. To prevent this: 1. 1.
### 4.1 Sign Up for BetterStack or UptimeRobot 1.
Choose one: 1.
- **https://betterstack.com** (recommended)
- **https://uptimerobot.com** (alternative)
Both offer free monitoring with no credit card required. 1. 1.
### 4.2 Create an Uptime Monitor 1.
1. In BetterStack/UptimeRobot, create a new monitor 1.
2. Settings: 1.
- **URL:** Your HuggingFace Space URL + `/api/v1/status`
``` 1.
https://YOUR-USERNAME-aiostreams.hf.space/api/v1/status 1.
``` 1.
- **Check frequency:** Every 10 minutes
- **Monitor type:** HTTP(S)
3. Save the monitor 1. 1.
This will ping your instance every 10 minutes to keep it awake! 1. 1.
## Step 5: Use Your Self-Hosted AIOStreams 1. 1.
### 5.1 Get Your Addon Configuration URL 1.
Your addon configuration URL format is: 1.
``` 1.
https://YOUR-USERNAME-aiostreams.hf.space/YOUR-ADDON-PASSWORD/configure 1.
``` 1. 1.
**Example:** 1.
- If your BASE_URL is: `https://john123-aiostreams.hf.space`
- And your ADDON_PASSWORD is: `MyStreams2024!`
- Your configuration URL is:
``` 1.
https://john123-aiostreams.hf.space/MyStreams2024!/configure 1.
``` 1. 1.
### 5.2 Add to Stremio 1.
1. Open Stremio 1.
2. Go to **Addons** (puzzle piece icon) 1.
3. Paste your configuration URL in the search/URL bar 1.
4. Click **Install** 1.
5. Configure your preferences 1. 1.
## Updating AIOStreams 1. 1.
To update to the latest version: 1. 1.
1. Go to your HuggingFace Space 1.
2. Click on the `README.md` file 1.
3. Click "Edit" 1.
4. Make any minor change (add a space, extra line, etc.) 1.
5. Click "Commit changes to main" 1.
6. This will trigger a rebuild with the latest AIOStreams version 1. 1.
## Troubleshooting 1. 1.
### Space shows "Building" for too long 1.
- Wait up to 10 minutes. First builds can take time.
- Check the "Logs" tab for any errors
### "Missing environment variables" error 1.
- Make sure all **4 secrets** are added correctly:
- `DATABASE_URI`
- `ADDON_PASSWORD`
- `SECRET_KEY`
- `BASE_URL`
- Double-check the `BASE_URL` format: `https://username-spacename.hf.space` (no trailing slash)
### Can’t access the addon URL 1.
- Make sure the Space shows "**Running**" status
- Try accessing `https://YOUR-SPACE-URL/api/v1/status` first
- Check if your ADDON_PASSWORD has special characters - try a simpler password if issues persist
### Database connection errors 1.
- Verify your `DATABASE_URI` starts with `postgres://` (not `postgresql://`)
- Make sure the URI ends with `?sslmode=require`
- Check your Neon database is active (not paused)
### Space keeps sleeping despite monitoring 1.
- Verify your BetterStack/UptimeRobot monitor is active
- Make sure it’s pinging the `/api/v1/status` endpoint
- Check the monitor is set to ping every 10 minutes
## Quick Reference - Required Environment Variables 1. 1.
| Variable | Description | Example | 1.
|–––––|———––|———| 1.
| `DATABASE_URI` | Neon PostgreSQL connection string | `postgres://user:[email protected]/db?sslmode=require` | 1.
| `ADDON_PASSWORD` | Password to access your addon | `MySecurePass123!` | 1.
| `SECRET_KEY` | 64-character random hex string | `4f9a2b8e7c1d6f3a9b2e8c7d1f...` | 1.
| `BASE_URL` | Your HuggingFace Space URL | `https://username-aiostreams.hf.space` | 1. 1.
## Cost Summary 1. 1.
✅ **Neon Database:** FREE (500 MB storage, 5 GB data transfer/month) 1.
✅ **HuggingFace Space:** FREE (2 vCPU, 16 GB RAM) 1.
✅ **BetterStack/UptimeRobot:** FREE (up to 10-50 monitors) 1. 1.
**Total Cost: $0.00/month** 🎉 1. 1.
## Notes 1. 1.
- This setup is perfect for personal use and legal streaming
- Free tiers are generous enough for moderate usage
- All services can be upgraded later if needed
- Your data is stored in your own database, giving you full control
- Make sure to use this only for legal content
## Support 1. 1.
If you encounter issues: 1.
1. Check the HuggingFace Space **Logs** tab for error messages 1.
2. Verify all 4 environment variables are correctly set 1.
3. Visit the AIOStreams GitHub repository for additional help 1. 1.
Enjoy your self-hosted AIOStreams! 🚀