Get up and running with Hyrex in minutes.

​
Prerequisites

  • Python 3.11 or higher
  • PostgreSQL 12+ (for FOSS) or Hyrex Cloud account

​
1. Install Hyrex

pip install hyrex

​
2. Initialize a New Project

Use the interactive hyrex init command to set up a new project: 
hyrex init
This will guide you through:
  • Choosing a project name
  • Selecting between PostgreSQL (self-hosted) or Hyrex Cloud
  • Creating project files (.env, hyrex_app.py, tasks.py, requirements.txt, Dockerfile)
For manual database initialization (if needed): 
export HYREX_DATABASE_URL="postgresql://user:password@localhost/dbname"
hyrex init-db

​
3. Project Structure

After running hyrex init, you’ll have: 
your-project/
├── .env                # Environment configuration
├── hyrex_app.py       # Hyrex app configuration
├── tasks.py           # Task definitions
├── requirements.txt   # Python dependencies
└── Dockerfile         # Container configuration
Example tasks.py: 
from hyrex import HyrexRegistry
from pydantic import BaseModel

hy = HyrexRegistry()

class EmailContext(BaseModel):
    to: str
    subject: str
    body: str

@hy.task
def send_email(context: EmailContext):
    print(f"Sending email to {context.to}")
    # Your email logic here
    return {"sent": True}

​
4. Send Tasks

Queue tasks for execution: 
# Send a task to the default queue
task = send_email.send(EmailContext(
    to="user@example.com",
    subject="Welcome!",
    body="Thanks for signing up"
))
print(f"Task queued with ID: {task.id}")

# Send with custom configuration
task = send_email.with_config(
    queue="high-priority",
    max_retries=3,
    timeout_seconds=30
).send(EmailContext(
    to="user@example.com",
    subject="Urgent!",
    body="Important message"
))

​
5. Run Workers

Start workers to process tasks: 
hyrex run-worker hyrex_app:app

​
6. Monitor Tasks

Visit your dashboard at hyrex.io/cloud to monitor tasks in real-time.

​
Next Steps

Tasks

Learn about task configuration

Workflows

Build complex workflows

Examples

See real-world patterns

Production Guide

Deploy to production