Write your first workflow

Write a workflow with one agent step and one terminal, then run it. It is the smallest workflow that does anything.

minimal.dot

digraph hello {
  graph [version="1", entry="hello"]
  hello [tool_access="Read only", prompt="Reply with one sentence explaining the goal: {{ inputs.goal }}."]
  done [shape="Msquare"]
  hello -> done
}

hello is an agent step. It has the Read only tool access, so it can read files but cannot change them. Codex reads files through commands that its read-only sandbox prevents from writing. done is a terminal, and the edge between them is the whole route. Every other guide builds on this with more steps and edges.

Before you start

You need a harness you have signed in to, and a project in Orbital. Any project works. It does not need to be a Git repository, unless you run the example with Codex, which needs one. See Projects and folders.

1. Save the workflow

Download the example and unpack it into your workflow library, ~/.orbital/workflows/. Keep every relative path. You can also download minimal.dot on its own.

2. Validate it

orbital validate ~/.orbital/workflows/minimal.dot

Validation calls no agent.

3. Start a run

Choose New task and pick any project. Choose the minimal workflow and your harness. One project serves every example.

Pick the workflow and harness beside the goal box.

Set the goal to “Explain what a workflow is”, and start the run. The hello step returns a sentence, then done ends the run successfully.

Related

• Write prompts: read run values in a prompt.
• Add branches: send a run to different steps.
• Node types: the kinds of step you can add.
• Research report: a workflow that touches no code.
• Workflows: where Orbital finds workflows and how to validate them.