Put an AI Coding Agent on a Cron

What a cog is (answer first)

A cog is a managed coding-agent task worker. You pick a harness (the coding agent — Claude Code today), write the task in plain language, and choose when it runs: on demand, on a cron schedule, or from a webhook. The platform runs it on your box through the on-box workflow engine, captures the result, and shows you the run. Nobody else's servers touch your code or your keys.

Anatomy of a cog

A cog is a small record. The fields that matter:

Under the hood the harness runs as a plain shell step on the box — claude -p "<your task>" in the cog's workspace, with the task passed through the environment (never the command line, so it cannot be injected). There is no magic runtime; there is a box, a agent binary, and a task.

Create one

From the dashboard, open Cogs → New: two required fields (a name and a task), everything else defaulted sensibly. Or via the API:

# Create a cog that triages error logs each morning
POST /api/cogs
{
  "name": "log-triage",
  "task": "Read yesterday's errors in /var/log/app, group by cause, and open a draft PR fixing anything obvious.",
  "harness": "claude-code",
  "target_sandbox_id": "sandbox_ab12cd34",
  "trigger": { "cron": "0 8 * * 1-5", "timezone": "UTC" }
}

Run it immediately to see it work before you trust the schedule:

POST /api/cogs/{cog_id}/run   # dispatches to the box now

Schedule or trigger it

A cron trigger puts the cog on the platform scheduler: it dispatches the job at each due time, on your box, and records the run. Missed a window because the box was down? It fires once when it can — no backfill storm. A run still in flight when the next is due? The overlap is skipped and recorded, never silently doubled.

Prefer event-driven? Give the cog a webhook: it gets a single-use token, and a POST /api/cogs/{id}/fire with that token runs it. Wire it to a form submission, a calendar event, a queue — the cog reacts instead of polling.

Grant it exactly the tools it needs

A coding agent with no tools can only read and write files in its workspace. Real jobs need more — a shared task queue, a connected API. You grant those per cog, and the platform delivers the tool configuration to the box as a locked-down, root-owned file the agent reads at startup. Grant nothing and it gets nothing (that is the default).

Secrets are named, never pasted: the grant references a key name; the value is delivered off-band and never appears in the cog record, the command line, or the logs.

See and review the work

Every run — manual, scheduled, or webhook — lands in the Runs view with its source (cog:<id>:cron), status, and output. Status is honest: a run that finished shows completed, not a perpetual spinner — the platform reconciles each run against the box when you look. Artifacts the agent produced (a diff, a report) are attached to the run for review before anything lands.

GET /api/cogs/runs            # your runs, newest first, accurate status
GET /api/cogs/runs/{exec_id}  # one run + its artifacts

Autonomy and safety, on by default

A cog ships cautious. The defaults: draft, do not push; dry-run first; a per-run budget and timeout. A cog that opens a draft PR is useful and safe; a cog that force-pushes to main at 3am is not, and the defaults do not let it. You widen the leash deliberately, not by forgetting a setting — every safety default holds even if an environment variable is never set.

When a cog becomes a claw

A cog is a job. Some jobs become a role. When a cog has earned its keep — a run history you trust, a task it owns — it can graduate into a claw: a named, persistent AI employee with its own channel, memory, and a place on your My Staff roster. The cog was the probation period; the claw is the hire. Same engine, two grammars: a task worker you schedule, and an employee you manage.

Create your first cog → Deploy from the App Store →