Automation

Workspace automation is OpenAlice's way to let trading work continue when nobody is sitting in the terminal.

The model is deliberately concrete:

trigger
  -> workspace
  -> headless agent run
  -> files / git / tools
  -> Inbox report

The trigger can come from the workspace itself, through a scheduled issue, or from another system calling the workspace headless API. In both cases, the agent runs inside the same workspace repo a human would use interactively.

What Runs

A headless run is a one-shot invocation of an enabled agent CLI inside a workspace. It inherits the workspace's files, git history, agent configuration, tool injection, credentials, and local context.

Every async run is recorded in the headless task registry:

Field	Meaning
`taskId` / `wsId` / `agent`	Which run, which workspace, which CLI
`issueId`	Present when the run came from a scheduled issue
`prompt`	The full instruction given to the agent
`status`	`running`, then `done`, `failed`, or `interrupted`
`startedAt` / `durationMs` / `exitCode`	Timing and process outcome
`agentSessionId`	The agent CLI's own session id, when OpenAlice can detect it

The registry answers whether the process started, finished, timed out, or failed. The useful work product should be pushed to Inbox, usually with alice-workspace inbox push.

Self-Scheduled Issues

A workspace schedules work by writing an issue file:

.alice/issues/<id>.md

An issue without when is a normal board item. Add when, and the same issue becomes scheduled work. The schedule scanner reads workspace issue files roughly once a minute and fires due, non-terminal issues as headless runs.

.alice/issues/morning-scan.md:

---
title: Pre-market brief
status: todo
priority: high
when: { kind: cron, cron: "30 8 * * 1-5" }
what: >
  Pull pre-market movers and overnight news for my watchlist, write a short brief to
  research/premarket.md, then run: alice-workspace inbox push --doc research/premarket.md --comments "Pre-market brief".
agent: claude
---
Every trading morning at 08:30, assemble the pre-market picture before the open.

The filename stem is the issue id. The scanner keys its last-fired marker by that id, so do not rename a scheduled file unless you mean to create a fresh schedule.

Schedule Fields

Field	Required	Meaning
`when`	Yes for scheduled work	When to fire the issue
`what`	No	The standalone prompt handed to the headless run; falls back to title + body
`agent`	No	Which enabled CLI should run it; falls back to the workspace default

Supported when shapes:

Kind	Shape	Example	Behavior
`every`	`{ kind: every, every: "30m" }`	`30m`, `2h`, `1h30m`	Repeat on an interval. Runs on the next scan, then on the interval.
`cron`	`{ kind: cron, cron: "0 9 * * 1-5" }`	`0 9 * * 1-5`	5-field cron, wall-clock.
`at`	`{ kind: at, at: "2026-03-01T13:30:00Z" }`	ISO 8601	Run once at the timestamp.

Set the issue status to done or canceled to stop a schedule without deleting the issue. Delete the file to remove the issue entirely.

Writing the Prompt

The what field should read like a complete handoff to a teammate who only has this workspace. Name the files to inspect, the decision criteria, and the expected output.

Good scheduled prompts usually say:

What context to read.
What condition to check.
What file to write or update.
When to push to Inbox.
When to exit silently.

There is no separate condition field. For "only alert me if X", write that logic into what: check X; if it matters, push an Inbox report; otherwise do nothing.

How a Scheduled Issue Fires

scanner tick
  -> read .alice/issues/*.md
  -> find a due issue with `when`
  -> dispatch a headless run in that workspace
  -> record taskId + status
  -> agent works in the repo
  -> agent pushes an Inbox report

The scanner stores only a last-fired marker: (workspaceId, issueId) -> timestamp. Schedule meaning stays in the issue file. If capacity is full, the issue is not marked as fired, so it can retry on a later scan.

Scheduled runs are independent. A scheduled run can overlap with another run or an interactive session in the same checkout, so write prompts as if concurrent file edits are possible.

Webhook

Other agents and external systems can ask a workspace to run through the workspace webhook:

POST /api/workspaces/:id/headless

This is useful when another AI system, local script, monitor, or scheduler should delegate work into an OpenAlice workspace instead of editing the workspace files itself.

See Webhook for the API contract and examples.

Security

Anyone who can call the headless endpoint can request arbitrary AI work in that workspace. Treat access as agent-level access.

Keep Alice bound to localhost unless you are using the admin-token and reverse-proxy setup described in Remote Access. If another agent runs on the same machine, localhost access is usually enough. If it runs elsewhere, put Alice behind TLS and keep the admin token scoped like a production secret.

UI Surfaces

Workspace automation shows up in three places:

Surface	What it shows
Issue Board	Scheduled issues, cadence pills, last fired, next due
Runs panel	Headless run status, prompt, agent, duration, and output tails
Inbox	The durable reports produced by scheduled or externally triggered runs

Next Steps

Issue Board - Add when and what to turn an issue into scheduled work.
Webhook - Trigger a workspace from another agent or external system.
Self-Describing Issues - Understand the issue file contract.
Inbox - Read the reports automation produces.
Workspaces - Understand the repo each run executes inside.

Search Documentation