README.md

metadata

title: VPS Linux
emoji: 🐨
colorFrom: red
colorTo: green
sdk: docker
pinned: false
license: mit

Simplified Linux VPS on Hugging Face Spaces

This project provides a simplified Linux VPS on Hugging Face Spaces with:

• Debian Bookworm Slim base
• Browser terminal powered by ttyd
• GitHub & Google OAuth authentication via nginx + oauth2-proxy
• Simple allowlist control

Users can access the Linux terminal only after successful GitHub or Google login.

🚀 Quick Start

1) Create a Hugging Face Space

1. Log in to Hugging Face.
2. Click your avatar in the top right corner and choose New Space.
3. Enter a Space name (for example: my-linux-vps).
4. Select SDK: Docker.
5. Select Docker Template: Blank.
6. Click Create Space.

2) Upload project files

Upload all files from this folder to your Space repository.

3) Configure Variables and Secrets

In Space Settings -> Variables and Secrets, add:

Variables

• SPACE_PUBLIC_URL=https://<your-space-name>.hf.space
• ALLOWED_USERS=user1@gmail.com,github_username_1 (Supports GitHub/Google email addresses or GitHub usernames)

Secrets

• GITHUB_CLIENT_ID=<github oauth app client id>
• GITHUB_CLIENT_SECRET=<github oauth app client secret>
• GOOGLE_CLIENT_ID=<google oauth client id>
• GOOGLE_CLIENT_SECRET=<google oauth client secret>
• OAUTH2_PROXY_COOKIE_SECRET=<32-byte-base64-secret>

Requirements:

• Secret values must be plain text (no quotes, no leading/trailing spaces).
• SPACE_PUBLIC_URL must not include a trailing slash.

4) Configure OAuth callbacks

GitHub OAuth App:

• Callback URL: https://<your-space-name>.hf.space/oauth2/github/callback
• Scope: user:email

Google OAuth Client:

• Authorized Redirect URI: https://<your-space-name>.hf.space/oauth2/google/callback
• Scope: email profile openid

SPACE_PUBLIC_URL and callback domain must match exactly.

5) Access the VPS

1. Wait until the Space status is Running.
2. Open the App tab.
3. Sign in with GitHub or Google.
4. After successful authentication, the web terminal will be available.

🛠️ Features

• Base system: Debian Bookworm Slim
• Privileges: default user has passwordless sudo
• Toolchain: git, curl, wget, vim, nano, build-essential, cmake
• Web terminal: ttyd
• Authentication: nginx + oauth2-proxy (GitHub & Google)
• Allowlist: supports emails and GitHub usernames in ALLOWED_USERS

🎮 How to Build OpenClaw

OpenClaw needs extra dependencies. Hugging Face Spaces has no native display, so GUI execution usually fails unless you set up VNC/X11 manually.

Install dependencies

sudo apt-get update
sudo apt-get install -y \
    libsdl2-dev \
    libsdl2-image-dev \
    libsdl2-mixer-dev \
    libsdl2-ttf-dev \
    libxml2-dev \
    zlib1g-dev

Clone and compile

git clone https://github.com/pjasicek/OpenClaw.git
cd OpenClaw
mkdir build && cd build
cmake ..
make -j$(nproc)

Notes

• Running ./OpenClaw may fail with Could not initialize SDL: No available video device.
• After Space restart, files outside /data may be lost. Save important data in /data (if persistent storage is enabled) or sync with Git.
• Troubleshooting 500 Errors: If you encounter a 500 error during login, ensure you have removed any legacy OAUTH2_PROXY_GITHUB_ORG variables from Space Settings, revoke the GitHub App authorization, and clear your browser cookies.

⚠️ Security Warning

• This VPS has elevated privileges. Do not store sensitive keys inside it.
• Public Spaces are accessible unless protected. This project protects terminal access with GitHub OAuth and allowlist rules.