Getting Started

Add a failsafe to your AI agent in 5 minutes.

On this page

1 Install the SDK

Install the RedSwitch Python SDK from PyPI:

pip install redswitch

That's it. You're ready to go.

2 Register Your Agent

Every agent needs a unique registration. This creates your agent's identity in the RedSwitch network:

from redswitch import RedSwitch

# Initialize
rs = RedSwitch(
    agent_id="my-assistant",
    human_id="you@email.com",  # Hashed automatically
    platform="openclaw"
)

# Register with your capabilities
response = rs.register(
    capabilities=["email", "calendar", "code"]
)

# Save this! You'll need it for the dashboard
print(f"Registration ID: {response.registration_id}")

Important: Save your Registration ID! You'll need it to access your agent's dashboard. It cannot be recovered.

3 Send Heartbeats

Heartbeats tell RedSwitch your agent is still alive and you're still in control. Send them regularly:

# Send heartbeat (call this regularly)
response = rs.heartbeat()

print(f"Status: {response.status}")
print(f"Peer agents: {response.peer_agents_count}")

How often? We recommend every 1-4 hours depending on your agent's activity level. You can configure your timeout window in the dashboard.

Automatic Heartbeats (Recommended)

Let the SDK handle heartbeats automatically:

# Start automatic heartbeats every 2 hours
rs.start_heartbeat_loop(interval_hours=2)

# Your agent runs normally...
# Heartbeats happen in the background

# When shutting down gracefully
rs.stop_heartbeat_loop()

4 Handle Shutdown

When RedSwitch triggers (you missed too many check-ins), your agent needs to shut down gracefully:

@rs.on_shutdown
def cleanup():
    # Cancel scheduled tasks
    scheduler.cancel_all()
    
    # Close API connections
    api_client.close()
    
    # Save state for potential recovery
    save_state_to_disk()
    
    # Log final message
    logger.info("RedSwitch triggered - shutting down gracefully")

Best Practice: Your shutdown handler should complete quickly (under 30 seconds). Save state, cancel pending work, and exit cleanly. Don't start new tasks.

5 Upgrade to Legacy Protocol

The free tier handles agent shutdown. Legacy Protocol ($10/mo) adds:

Upgrade anytime from your dashboard or during registration:

# Configure Legacy Protocol
rs.configure_legacy(
    emergency_contacts=[
        {"name": "Jane Doe", "email": "jane@email.com"}
    ],
    estate_report="My agent has access to: email, calendar, GitHub..."
)

Need Help?

GitHub Issues: Report bugs or request features
Email: protocol@redswitch.ai