Background job orchestration for your monorepo.
Use GitHub Actions for deploys. Use Cinnamon for everything else.

---

• Config-driven -- define jobs in cinnamon.config.ts, point them at any package in your monorepo
• Language-agnostic -- Python, Bash, Node, Bun, or any shell command
• Scheduled + on-demand -- cron expressions, CLI triggers, or HTTP API
• Durable -- every run logged to Postgres with stdout, stderr, timing, and structured results
• Observable -- built-in dashboard with live log streaming
• Notifiable -- Slack, Discord, or webhook alerts on success or failure

Quick start

Requires Bun and Docker.

bun create cinnamon my-app
cd my-app
bun run dev

Open the dashboard at http://localhost:3000. See the full setup guide for db:migrate, seed:team, and CLI configuration.

Add a job

Three steps: config, script, trigger.

1. Define the job in cinnamon.config.ts:

import { defineConfig } from "./config/define-config.ts";

export default defineConfig({
  jobs: {
    "nightly-sync": {
      command: "bun",
      args: ["run", "sync"],
      cwd: "./packages/data",
      schedule: "0 2 * * *",
      timeout: "5m",
      description: "Sync data from upstream API",
      notifications: {
        on_failure: [{ url: "${DISCORD_WEBHOOK_URL}" }],
      },
    },
  },
});

Any command that runs in a shell works -- python3, bash, bun, node, curl, etc. Use cwd to target a specific package in your monorepo.

2. Create the script in your package:

# jobs/nightly-sync/sync.py
import json

result = {"synced": 1420, "status": "ok"}
print(json.dumps(result))  # last JSON line → stored in jobs_log.result

3. Trigger it:

cinnamon trigger nightly-sync     # CLI
# or
curl -X POST http://localhost:3000/v1/jobs/nightly-sync/trigger \
  -H "Authorization: Bearer cin_<your_key>"

Jobs with a schedule field run automatically via cron. See Jobs and config and Writing scripts for the full spec.

Architecture

flowchart LR
  CLI["CLI"] --> Queue["BullMQ (Redis)"]
  API["API server (Hono)"] -->|"POST /v1/jobs/:name/trigger"| Queue
  Dashboard["Dashboard (React)"] -->|"/api/dashboard/*"| API
  Queue --> Worker[worker]
  Worker --> Handler[job handler]
  Worker --> JobsLog["cinnamon.jobs_log (Postgres)"]

Loading

Docs

Topic	Description
API reference	Endpoints, query params, curl examples
Jobs and config	Job definitions, cinnamon.config.ts
Writing scripts	Output contract for shell scripts
Dashboard auth	Google OAuth setup and session management
Access requests	Self-service access request flow
Deployment	Docker Compose and CI/CD
Migrations	Schema namespacing, migration patterns
Project structure	Directory layout, scripts, CLI
Resilience	Zombie cleanup and worker self-healing
Postgres	Health checks, SQL shell
Redis	Health checks, debugging
Tests	Test coverage and details
Examples	Reference implementations (Spotify, deploy configs)

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT