Jobs & runners — Corotation docs

A script. A runner. Automatic builds.

Jobs run after changes reach current. Write an ordinary script, then enable it once. Runners can live on your laptop, on the server, or on separate machines.

cor jobs add release
cor runner
cor jobs

Setup suggests your script, selects target platforms, and remembers the remote and runner settings. Keep cor work running to synchronize your scripts and source. Jobs do not publish local edits themselves.

Write a job

#!/bin/sh
set -eu
cargo build --release --locked
cp "$CARGO_TARGET_DIR/my-game" "$LAPLACE_OUTPUT/my-game"

The working directory is a fixed source snapshot. LAPLACE_CACHE and LAPLACE_STATE persist on that runner. LAPLACE_OUTPUT collects artifacts. LAPLACE_CONTEXT points to JSON with the source sequence, triggering changes, SSH authors, and session tags. Exit zero to succeed.

One snapshot, several machines

Choose linux-x86_64,macos-arm64 during setup, then run cor runner in a connected project on each machine. All targets build the same snapshot. Artifacts become available when every target succeeds. Each runner uses one execution slot and outbound SSH; it needs no incoming port.

On macOS, the background runner starts at login using a LaunchAgent. Linux uses a systemd user service. Use --foreground with another supervisor. cor runner stop works offline and disables startup; cor runner settings shows saved defaults.

Tune what triggers a run

[jobs.release]
on = "published"
run = ["sh", "scripts/release.sh"]
inputs = ["src/**", "assets/**", "Cargo.*", "scripts/**"]
quiet = "30s"
max_wait = "2m"
timeout = "30m"
targets = ["linux-x86_64", "macos-arm64"]

Definitions are inert until explicitly enabled. After editing, run cor jobs enable release. Use on = "manual" for manual jobs. Exclude paths with a leading !. Changes during a build become one pending batch. Retries retain the original definition and snapshot.

Inspect a run

cor jobs logs release --follow
cor jobs run release
cor jobs retry 42
cor jobs artifacts 42
cor jobs disable release
cor jobs runners

Logs keep the latest 128 KiB per task and update every ten seconds. Save full logs as artifacts when needed. Downloads default to a new temporary folder; --output selects a new folder outside your synchronized source. Artifacts support up to 1,000 files and 10 GiB per task. Add --json for scripting.

Choose where scripts can run

First setup offers trusted native execution or a Docker image. Native scripts run with your account’s filesystem and network access. Docker uses a pinned local image without network or host credentials, and mounts only source, cache, state, output, and context. Pull a prepared image before selecting it.

Runners have separate SSH keys scoped to a repository and, optionally, named jobs. They cannot publish source or manage jobs. Use cor runner --jobs release to narrow the scope, or revoke a key with cor jobs runners --revoke FINGERPRINT.

Builds survive interruptions

Runners reuse chunks, unchanged source timestamps, and compiler caches. Incoming saves never change an active build. A disconnected runner loses its lease; expired tasks can be reassigned up to three attempts. Attempt tokens reject stale results. Use LAPLACE_TASK_ID to make external publication idempotent: shell side effects may happen more than once.

History, artifacts, and caches have no automatic garbage collection yet. Back up current’s database and jobs directory and monitor disk space. Runner state is local to its machine; a shared release decision needs durable shared storage.

Read the complete script contract and operational reference ↗