CUSTOSBack to home

Self-Hosting Guide

For developers who want to run Custos on their own infrastructure.

⚠️ This guide is for developers. Self-hosting requires Python, Docker, terminal commands, and your own OpenAI API key. This is not the standard Custos experience.

Not a developer? Start your free trial for the one-click install experience—no technical setup required.

Prerequisites

  • •
    Python 3.11+

    Required for the desktop client and server.

  • •
    Docker & Docker Compose

    For running the server (optional but recommended).

  • •
    OpenAI API Key

    For the Guardian AI. Get one at platform.openai.com

  • •
    ~2GB Disk Space

    For the CLIP model and dependencies.

Step 1: Clone the Repository

Terminal
git clone https://github.com/blueskylineassets/custos.git
cd custos

Step 2: Configure Environment

Copy the example environment file and add your OpenAI API key:

Terminal
cp .env.example .env
nano .env  # or use your preferred editor

Edit the .env file:

.env
# Required
OPENAI_API_KEY=sk-your-openai-api-key-here

# Optional: Personalization
USER_NAME=Pilgrim
PROTEGE_NAME=Your Future Family
TARGET_DATE=  # YYYY-MM-DD or leave empty

# Optional: Adjust sensitivity
CLIP_THRESHOLD=0.25

Step 3: Start the Server

Using Docker Compose (recommended):

Terminal
cd server
docker-compose up --build -d

Or without Docker (requires Python 3.11+):

Terminal
cd server
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
python main.py

The server will be available at http://localhost:8000

Step 4: Run the Desktop Client

Terminal
cd desktop_client
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
python main.py

The Guardian will start monitoring your screen. It will run in the background.

Step 5: Configure Auto-Start (Optional)

To have Custos start automatically when you log in:

macOS

Use the included start.sh script or create a LaunchAgent.

Windows

Use the included start.bat script or add to Startup folder.

Linux

Create a systemd user service. See the README for details.

Troubleshooting

CLIP model download is slow

The first run downloads ~500MB for the CLIP model. This is a one-time download. If it fails, check your internet connection and try again.

OpenAI API errors

Make sure your API key is valid and has credits. The Guardian uses GPT-4o, which requires a paid OpenAI account.

Screen capture permissions (macOS)

On macOS, you need to grant Screen Recording permission to the terminal/Python. Go to System Preferences → Privacy & Security → Screen Recording.

Need Help?

Reach out to us or consider upgrading to The Patron for priority support.

Contact SupportUpgrade to Patron