In a growing team, this issue scales rapidly. Forgotten staging environments and idle development servers can easily account for 60% to 80% of a company’s cloud computing waste.

To solve this, we looked at the existing solutions:

1. AWS Instance Scheduler: A powerful tool, but setting it up requires complex CloudFormation templates, DynamoDB tables, Lambda configurations, and heavy maintenance.

2. SaaS Platforms: These services request extensive IAM permissions to your AWS accounts and charge monthly fees, which defeats the purpose of saving money.

We wanted something simple, lightweight, visual, and secure. That's why we built CloudNap—an open-source, self-hosted AWS sleep scheduler that runs inside a single Docker container.

In this article, we'll walk through how it works, its architecture, and how it can help you automate cost optimization.

🛠️ The Architecture of CloudNap

CloudNap is designed to be low-maintenance and easy to deploy:

• FastAPI Backend (Python): Handles REST API routing, manages configuration settings, and communicates with the AWS API using boto3.

• State-Based Self-Healing Engine: Driven by APScheduler, this background worker runs every minute to evaluate and enforce the target power state.

• SQLite Database: A simple, persistent database that stores your resources, sleep schedules, action logs, and manual overrides.

• React Frontend SPA (Vite): A responsive cost-control dashboard styled using a premium light theme.

🚀 Key Features That Solve Real Cost Problems

1. State-Based Self-Healing (Not Event-Based)

Traditional schedulers often trigger a "stop" command at a specific time (e.g., exactly at 22:00 UTC). If your scheduler is down at that minute, or if a developer manually turns the instance back on at 22:05, the server will run all night.

CloudNap uses a range-based state evaluation model. Every minute, the scheduler checks if now falls inside a sleep window. If a developer manually starts an instance during its sleep window without setting an override, CloudNap automatically turns it back off (self-healing) within a minute.

2. Flexible Sleep Schedules (One-time, Daily, Weekly)

Developers can configure scheduling rules that fit their workflows:

• One-time Sleep Windows: Specify a precise start and end date/time (e.g., from Friday 18:00 UTC to Monday 08:00 UTC).

• Recurring Sleep Windows: Configure daily or weekly repeat schedules (e.g., shutdown every day at 22:00, or run only on specific weekdays).

3. Resource Lease Expiry (TTL)

When you hand over a server to a developer for a temporary project (e.g., a 2-week sprint), you can configure a Lease Expiry Date/Time (TTL).

Once the lease expires, CloudNap automatically shuts down the instance, locks it in a stopped state, and prevents automated schedules from turning it back on.

4. Interactive Manual Holds

If a developer needs to work late, they don't have to delete their schedules. They can simply click "Stop Instance Manually" or "Start Instance Manually" to apply a state override. CloudNap locks that state and pauses automated schedules until the developer clicks "Resume Schedule".

5. Slack & Telegram Integrations

CloudNap sends real-time notifications for every action: schedule creations, manual overrides, and system-initiated shutdowns. You can configure credentials directly on the settings page and use the built-in "Test Connection" buttons to verify webhook and telegram bot configurations instantly.

6. Developer-Friendly Mock Mode

To encourage open-source contributions and local testing, CloudNap features a full AWS mock mode. By launching with MOCK_AWS=true, the application simulates active AWS instances and state transitions in memory. Developers can run and test the entire project without needing AWS credentials or incurring charges.

⚡ Quick Start: Running CloudNap

You can launch the entire stack locally in less than 30 seconds using Docker Compose:

1. Clone the repository:

   git clone https://github.com/your-username/cloudnap.git
   cd cloudnap
   

2. Configure environment variables: Create a .env file in the backend/ directory:

   MOCK_AWS=true
   APP_PASSWORD=secret123
   DATABASE_URL=sqlite:///./data/cloudnap.db
   

3. Launch the container:

   docker compose up --build -d
   

4. Open http://localhost:8000 and log in with your configured APP_PASSWORD.

🤝 Open Source & Contributing

CloudNap is open-source under the MIT License. We welcome pull requests, bug reports, and suggestions.

Check out the repository, star the project if you find it useful, and let us know what features we should build next!

👉 GitHub Repository: https://github.com/famirco/cloudnap