Schedule a nightly report

This guide is for developers automating recurring work: a nightly export, a daily digest, a weekly reconciliation. Prerequisites: CYCLS_API_KEY.

1. Write the job

A scheduled function is called with no arguments, so it computes its own parameters.

reports.py

import datetime

import cycls

reports = cycls.Volume("reports")
image = cycls.Image().pip("duckdb", "openpyxl")


@cycls.function(
    image=image,
    volumes={"/reports": reports},
    schedule=cycls.Cron("0 6 * * *", timezone="Asia/Riyadh"),
    memory="2Gi",
    timeout=1200,
)
def daily_sales():
    import pathlib
    import duckdb

    day = (datetime.date.today() - datetime.timedelta(days=1)).isoformat()
    out = pathlib.Path(f"/reports/sales/{day}.xlsx")
    out.parent.mkdir(parents=True, exist_ok=True)

    con = duckdb.connect()
    con.execute("INSTALL excel; LOAD excel;")
    con.execute(
        f"""
        COPY (
            SELECT country, sum(amount) AS revenue, count(*) AS orders
            FROM read_parquet('/reports/events/*.parquet')
            WHERE day = '{day}'
            GROUP BY 1 ORDER BY revenue DESC
        ) TO '{out}' (FORMAT xlsx, HEADER true)
        """
    )
    return {"day": day, "path": str(out)}

2. Test before scheduling

cycls run reports.py::daily_sales

The schedule does not fire during cycls run. The local run executes the function once so you can check the output.

3. Deploy

cycls deploy reports.py
#   [DEPLOYING] Scheduled: 0 6 * * * (Asia/Riyadh)
#   [DONE] Deployment complete!

The deploy output confirms the schedule. From then on the platform calls the function, with no worker of yours to keep running.

4. Confirm it runs

cycls logs daily-sales -s 24h
cycls volume ls reports sales/

Every fire is an ordinary request, so it appears in logs like any other call.

5. Change or remove the schedule

Source is the truth. Edit the cron expression and redeploy to change it. Delete the schedule= argument and redeploy to remove it, which the deploy output confirms with Schedule removed. cycls rm removes both the deployment and its schedule.

6. Hand the report to users

Point an agent at the same volume and let it read the files.

assistant.py

import cycls

reports = cycls.Volume("reports")

llm = (
    cycls.LLM()
    .model("anthropic/claude-sonnet-4-6")
    .system(
        "Daily sales reports are at /reports/sales/<date>.xlsx. "
        "Read the requested day and summarize it. Open the file on the canvas."
    )
    .allowed_tools(["Bash", "Editor", "Canvas"])
)


@cycls.agent(
    image=cycls.Image().copy(".providers.env", ".env"),
    web=cycls.Web().auth(cycls.Clerk()).title("Sales assistant"),
    volumes={
        "/workspace": cycls.Volume("assistant-chats"),
        "/reports": reports.read_only(),
    },
)
async def assistant(context):
    async for ev in llm.run(context=context):
        yield ev

The read-only mount means the agent can read every report and change none of them.

Writing safe scheduled jobs

Property	What it means for your code
At least once	A run can fire twice. Key output by date so a rerun overwrites rather than appends
Runs can overlap	A slow run does not block the next. Take a lock file on the volume if two runs must never race
Thirty minute ceiling	Split long work, or have the scheduled function call `map()` and return quickly
No pause button	Remove `schedule=` and redeploy, which is the only off switch

A safe job looks like this:

out = pathlib.Path(f"/reports/sales/{day}.xlsx")   # date-keyed, so reruns overwrite
if out.exists() and not force:
    return {"day": day, "status": "already done"}

What cannot be scheduled

Apps and agents. They serve HTTP. Schedule a function that calls them.
Functions that take a port. The port contract deploys a server, which a schedule cannot fire.

Both fail at import with the fix in the message.

Python reference

Every exported name in one table.

Get started

Functions

Apps

Agents

Interface and users

Ship it

Guides

Reference

Resources

For LLMs

Schedule a nightly report

1. Write the job

2. Test before scheduling

3. Deploy

4. Confirm it runs

5. Change or remove the schedule

6. Hand the report to users

Writing safe scheduled jobs

What cannot be scheduled

Next

Python reference

​1. Write the job

​2. Test before scheduling

​3. Deploy

​4. Confirm it runs

​5. Change or remove the schedule

​6. Hand the report to users

​Writing safe scheduled jobs

​What cannot be scheduled

​Next

Python reference

1. Write the job

2. Test before scheduling

3. Deploy

4. Confirm it runs

5. Change or remove the schedule

6. Hand the report to users

Writing safe scheduled jobs

What cannot be scheduled

Next