# Cron

**Page:** kit/cron

[Download Raw Markdown](./kit/cron.md)

---

**Cron-as-a-service.** Hoody Cron wraps the system crontab in a REST API with managed entries, enable/disable toggles, auto-expiration, and per-user isolation. Standard 5-field cron expressions plus macros like `@hourly` and `@daily`.


**Managed Entries**: JSON-based CRUD with UUIDs, comments, enable/disable, and auto-expiration. The API injects entries into the system crontab with tracking metadata.

**Raw Crontab**: Full read/write access to the raw crontab file per user. Use this when you need complete control or have existing crontab workflows.


## What You Can Do

- **Managed Entries** - Create, update, delete cron jobs via JSON API with UUIDs
- **Enable/Disable** - Toggle jobs on and off without deleting them
- **Auto-Expiration** - Set `expires_at` for temporary jobs that clean themselves up
- **Per-User Isolation** - Each system user has their own crontab
- **Raw Crontab** - Read and write the full crontab file directly
- **Standard Cron** - 5-field expressions (`* * * * *`) plus macros (`@hourly`, `@daily`, `@weekly`, `@monthly`, `@yearly`)
- **Comments & Metadata** - Attach human-readable comments to managed entries

## API Endpoints Summary

All endpoints accessed relative to your Cron service URL:
```
https://PROJECT_ID-CONTAINER_ID-cron-1.SERVER.containers.hoody.icu
```

**Managed Entries**:
- [`GET /users/{user}/entries`](/api/cron/entries/) - List managed entries for a user
- [`POST /users/{user}/entries`](/api/cron/entries/) - Create a new managed entry
- [`GET /users/{user}/entries/{id}`](/api/cron/entries/) - Get a specific entry
- [`PATCH /users/{user}/entries/{id}`](/api/cron/entries/) - Update an entry
- [`DELETE /users/{user}/entries/{id}`](/api/cron/entries/) - Delete an entry

**Raw Crontab**:
- [`GET /crontab`](/api/cron/crontab/) - List all user crontabs
- [`GET /users/{user}/crontab`](/api/cron/crontab/) - Get raw crontab for a user
- [`PUT /users/{user}/crontab`](/api/cron/crontab/) - Replace raw crontab for a user

**System**:
- [`GET /health`](/api/cron/) - Health check

## Quick Start: Create a Scheduled Job


  
    ```bash
    # Create a cron job that runs daily at 9 AM
    hoody cron entries create root \
      --schedule "0 9 * * *" \
      --command "/usr/local/bin/backup.sh" \
      --comment "Daily backup at 9 AM"

    # List all cron entries
    hoody cron entries list root

    # Update a job's schedule
    hoody cron entries update root $ENTRY_ID \
      --schedule "0 12 * * *"

    # View the raw crontab
    hoody cron crontabs get root
    ```
  
  
    ```typescript
    import { HoodyClient } from '@hoody-ai/hoody-sdk';

    const client = new HoodyClient({ baseURL: 'https://api.hoody.icu', token: process.env.HOODY_TOKEN });
    const containerClient = await client.withContainer({ id: CONTAINER_ID, project_id: PROJECT_ID, server: SERVER });

    // Create a daily cron job
    const entry = await containerClient.cron.entries.create('root', {
      schedule: '0 9 * * *',
      command: '/usr/local/bin/backup.sh',
      comment: 'Daily backup at 9 AM',
      enabled: true,
    });

    // List all entries
    const entries = await containerClient.cron.entries.list('root');

    // Disable temporarily
    await containerClient.cron.entries.update('root', entryId, {
      enabled: false,
    });
    ```
  
  
    ```bash
    # Create a daily cron job
    curl -X POST "https://PROJECT-CONTAINER-cron-1.SERVER.containers.hoody.icu/users/root/entries" \
      -H "Content-Type: application/json" \
      -d '{
        "schedule": "0 9 * * *",
        "command": "/usr/local/bin/backup.sh",
        "comment": "Daily backup at 9 AM",
        "enabled": true
      }'

    # List all entries
    curl "https://PROJECT-CONTAINER-cron-1.SERVER.containers.hoody.icu/users/root/entries"

    # Disable a job
    curl -X PATCH "https://PROJECT-CONTAINER-cron-1.SERVER.containers.hoody.icu/users/root/entries/$ENTRY_ID" \
      -H "Content-Type: application/json" \
      -d '{"enabled": false}'
    ```
  


**1. Create a managed cron entry:**



**2. List all managed entries:**



**3. Disable a job temporarily:**



## Cron Schedule Reference

Standard 5-field cron expressions:

```
┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sun=0)
│ │ │ │ │
* * * * *
```

**Common patterns:**
| Schedule | Expression |
|---|---|
| Every minute | `* * * * *` |
| Every hour | `0 * * * *` |
| Every day at midnight | `0 0 * * *` |
| Weekdays at 9 AM | `0 9 * * 1-5` |
| Every Sunday at 3 AM | `0 3 * * 0` |
| First day of month | `0 0 1 * *` |

**Macros:** `@yearly`, `@monthly`, `@weekly`, `@daily`, `@hourly`

## Auto-Expiration

Set `expires_at` on managed entries for temporary jobs that automatically remove themselves:

> /var/log/health.log",
  "comment": "Temporary health monitoring - auto-expires",
  "enabled": true,
  "expires_at": "2025-01-02T00:00:00Z"
}'
/>

## Raw Crontab Access

For full control, read and write the raw crontab directly:

**Read the current crontab:**



**Replace the entire crontab:**



## Use Cases

- **Scheduled backups** - Run backup scripts at regular intervals
- **Data processing** - ETL jobs, report generation, log rotation
- **Health monitoring** - Periodic health checks with auto-expiring entries
- **Temporary tasks** - Time-limited monitoring or data collection
- **Maintenance** - Cache cleanup, database optimization, certificate renewal

## What's Next

- [Cron API Reference](/api/cron/) - Complete API documentation
- [Managed Entries API](/api/cron/entries/) - CRUD operations for managed entries
- [Raw Crontab API](/api/cron/crontab/) - Direct crontab file access
- [Daemons](/kit/daemons/) - For always-running processes (vs scheduled tasks)
- [Exec](/kit/exec/) - Execute scripts as HTTP endpoints