devmachine

How it works

Scheduled tasks

devmachine scheduled runs a shell command, or a prompt for a coding agent, in a folder of a workspace, on a schedule: once, every hour, every day, on weekdays, every week or every month. The macOS app shows the same tasks on its Scheduled page. For examples and how to set one up, see the scheduled tasks guide.

Each workspace runs its own tasks

A task lives in the workspace that runs it, under ~/.devmachine/scheduled/. Nothing on your computer has to be awake when it runs, and no machine reaches into another machine to start it.

The other way, one machine that starts every task everywhere, needs that machine to hold a login to every other workspace. Today only your computer holds those logins, and that is on purpose. The list still reads as one, because devmachine scheduled list asks every workspace at once, the way devmachine sessions does.

One timer, tasks in files

The scheduled package installs one timer per workspace that fires every minute and runs devmachine scheduled local tick. On Linux it is a user systemd timer, with linger so it runs with nobody logged in. On macOS it is a launch daemon that runs as the workspace’s account.

Each tick reads the task files and starts what became due since the last tick. Creating, changing or pausing a task only writes a file: no root, no reload, and the same on both systems. One timer per task would need root on macOS for every change.

The workspace runs the same devmachine

The package puts the devmachine binary in the workspace and links it at ~/.devmachine/scheduled/devmachine. The timer and your computer both call that path. Deciding when a task is due, building the agent’s command and keeping the record of each run is the same Go code you run on your computer.

Your computer reaches it as sessions does: it logs in to the workspace and sends a short program to /bin/sh on its input, so the account’s own shell, which may be fish, never reads a task’s text.

A setup that did not finish

The first task in a workspace adds the scheduled package to it and syncs its machine. If that sync fails, the package stays in the configuration and the binary is not in the workspace.

It stays on purpose. Taking it off would undo the one part that worked, and the next attempt would add it again anyway. So the CLI never trusts the configuration alone. Before each call it checks the binary is there. When it is not, but the package is in the configuration, the error says setup-incomplete and names the sync that finishes it: devmachine sync --machine <m> --tags scheduled. scheduled add runs that sync itself, with the same --yes rule as the first setup, and then creates the task. scheduled list shows the workspace as not installed, with the same error, so the app can offer to finish the setup.

When the setup sync fails, the error names the Ansible task that failed and what it said. “1 task(s) failed” alone leaves you reading the whole run.

A task runs as the workspace’s account

The task runs in the folder you chose, as that account, through its login shell, so the tools mise or Homebrew put on its PATH are there. A prompt starts with that account’s Claude or Codex login, skills, MCP servers and connectors. A prompt that says “email me the summary” works when that account has an email connector, and does nothing more than the account can do.

The prompt reaches the agent as one argument. No shell reads it, so quotes, $(...) and new lines arrive as you wrote them. A command, on the other hand, is a shell line, and the shell reads it as one.

Permission modes

A prompt runs with nobody there to approve a tool. A mode that asks before it acts, such as Claude’s manual, stops at the first tool it needs and the run ends with nothing done. acceptEdits approves file edits only, so a call to a connector such as Linear or email is refused; auto lets the agent use its tools and connectors, and is what the app picks. A mode that never asks at all, bypassPermissions for Claude or danger-full-access for Codex, needs --allow-dangerous, so it is always a choice somebody made.

devmachine scheduled harnesses lists each agent’s modes and suggested models.

A missed run is recorded, not run

If the machine was off or asleep when a task was due, the next tick records one missed run and does not start it. Work that runs hours late tends to surprise more than it helps. A tick starts a task only when its time was in the last two minutes.

A one-off task that was missed is done, like one that ran.

No two runs of a task at once

A run holds a lock while it goes. If the next time comes while it still runs, that time is recorded as skipped. A lock left by a run that died, after a reboot for example, is taken over.

Each run is kept

A run records how it started (schedule or manual), when, how long it took, its exit code and how it ended: succeeded, failed, timeout, error, missed or skipped. Its output, stdout and stderr together, is kept up to the last mebibyte, where the error usually is. The last 50 runs of each task are kept.

A run stops after its timeout, 30 minutes unless the task says otherwise, at most 6 hours. Everything it started stops with it.

Run now

devmachine scheduled run starts the task in the workspace and returns at once with the run’s id. The run goes on after the command returns, and after you close the connection. Its schedule does not change, and a one-off task run this way still runs at its time.

Timezone

A task keeps the timezone it was created in, by default your computer’s. 09:00 in America/Sao_Paulo runs at 09:00 there, whatever the server’s own clock says, and across daylight saving changes. A monthly task on day 31 runs on the last day of shorter months.