Getting started

Install Orbital and authenticate a harness first. This graph asks for a sentence and makes no publication request.

Save and validate

Create a practice folder and its graph directory:

mkdir -p ~/orbital-practice/.orbital
git init ~/orbital-practice

Save the complete text below as ~/orbital-practice/.orbital/hello.dot:

digraph hello {
  graph [version="1", entry="hello"]
  hello [prompt="Reply with one sentence explaining the goal: {{ inputs.goal }}. Do not use tools or change files."]
  done [shape="Msquare"]
  hello -> done
}

orbital validate ~/orbital-practice/.orbital/hello.dot
orbital serve

Validation must succeed before you start the run. It reads the graph without calling an agent.

Create the project

Open the server’s printed address. In Projects, choose New project, name it Practice and create it. Open the project and choose Add folder. Select ~/orbital-practice on the server machine and confirm the folder name. The first folder becomes the primary working folder. This practice folder is a local Git repository, which Codex requires. No remote repository is needed.

Start the run

Choose New run. Select the Practice project, the hello graph and the harness you authenticated. Set the goal to Explain what a graph is in one sentence, then start the run. If a required input is missing, fill in the field named by the form before starting.

The run shows hello executing, the agent’s sentence, then the done terminal. Confirm the run ends successfully. A completed agent turn alone is not the completion criterion; the run must reach its terminal.

If it stops, open the failed step and read the reason. A missing CLI or login needs authentication recovery. Do not switch to a ticket workflow to debug the installation.

You can also create graphs in the browser’s graph library and edit their DOT. Saving validates the graph. Keep this first graph on disk so its path and CLI validation are easy to reproduce.

Next, read how the engine works, or add conditional routing to a graph of your own.