Run Koder on a schedule and in CI

Koder can work when you're not at the keyboard: on a schedule on your computer, or in scripts and CI jobs with koder run. This article explains how to create a scheduled task, what an unattended run may do, how to see and manage its runs, and how to set Koder up in a CI job.

Create a scheduled task

1. Open the command palette and choose Scheduled tasks, then select New task. You can also start from a template.
2. Give it a Name and the Instructions Koder should follow.
3. Choose the Model and the Agent.
4. Under Starts, choose On a schedule, When a file appears in a folder or When a script finds something.
5. For a schedule, choose how often it repeats and its Time zone.
6. Under Run in, choose A new session each run, This conversation or Another conversation.
7. Choose what the run may do, then save.

Schedules can repeat every few minutes, every hour, every day, on weekdays or weekends, weekly on the days you choose, or on your own cron expression. They keep the right hour when the clocks change.

In the terminal, use /schedule to schedule a task for the project, or /loop to repeat a prompt in the open chat. Run koder cron --help for the commands in your installed version.

What an unattended run may do

No one is there to approve a step, so you choose up front how much a scheduled run may do:

• Read-only (the default): reads and searches run. Anything else is skipped and recorded in the run's history.
• Auto: the run does what it needs inside the project, including sending through connected apps.

Whichever you choose, every deny rule still applies. Pushing code, deleting, spending money, submitting pages, reading secret files, touching files outside the project and changing schedules stay denied, and the run records why. A run sent into a conversation uses that conversation's permissions.

Manage scheduled tasks

Open Scheduled tasks to see each task and its runs. Each run shows its outcome, how many steps were denied and what it cost, and opens as a session.

• Run now: run a task once without waiting for its schedule.
• Pause and Resume: stop a task for a while and start it again.
• Edit: change its instructions, schedule or model.
• Remove schedule: delete the task.

When tasks run

A scheduled task runs only while aixplain Desktop, the koder terminal app or koder serve is open on your computer. It doesn't run while the computer is asleep.

• Keep this machine awake: keeps your computer from sleeping while tasks are due. A closed laptop lid still sleeps.
• Catch up once: runs a task once when the app opens, if it missed its time. Without it, a run missed by more than five minutes is skipped.

Up to four unattended runs can run at once, and each run stops after 30 minutes.

Run Koder in CI

koder run takes a prompt from the shell, so you can run the agent in scripts and CI. It waits for background work to finish before it exits, and exits with an error when a turn fails.

koder run "Explain this project"
koder run --agent plan "Plan how to add a CSV export to the reports page"
koder run --model <provider/model> "Summarize the changes on this branch"

To fail a job on security findings, run koder scan --fail-on high. See Find security issues with Scan.

Set up the job

• A supported runner: one of the CLI platforms, with curl and bash on macOS and Linux, or PowerShell on Windows.
• Install in the job: use the install commands in Get started with Koder. A CI step that runs in the same shell may not see the new PATH, so call ~/.koder/bin/koder directly or add that folder to the job's PATH.
• Sign in without a browser: set AIXPLAIN_API_KEY to an aixplain API key stored in your CI system's secrets, or run koder login --token. To use your own provider instead, set its key the same way.
• Pin a version: download the installer from that release's page on GitHub instead of latest.
• Check the job: run koder doctor to check the install, config and providers, and koder inspect to see the effective permission policy.

Limitations

• Scheduled tasks run only while the app, the terminal app or koder serve is open on an awake computer.
• A one-shot koder run doesn't run scheduled tasks.
• This article doesn't cover each CI system's own setup. Run koder <command> --help for the options in your installed version.

Troubleshooting

My scheduled task didn't run

Check that the app was open and the computer awake at the scheduled time. If it missed its time by more than five minutes, it was skipped; turn on Catch up once to run it when the app next opens.

A scheduled run skipped steps

The run's permissions denied them. Open the run to see what was denied and why, then change what the task may do if it needs more.

Why can't my CI job reach a model?

Run koder doctor in the job. It checks the install, config, storage, providers and recent logs, and warns when no provider is set up. Check that AIXPLAIN_API_KEY or your provider's key is set in the job, then run koder models to see which models the job can reach. A local model must run on the CI runner itself.

Get help

• Report a problem: email care@aixplain.com with your Koder version, the command and what happened.
• See what changed: read the release notes.