Agents and Coding
Agents and Coding are in the Build group. Agents is who does the work; Coding is where that work lands as code. Both show the organization the window is in. The concepts behind them are in Staff and agents, Coding agents and Run a ticket.
Agents
The section has an organization tree on the left, a list in the middle and the open item on the right. The tree starts with This computer, then Organization (with the actor count) and its units. Selecting a unit scopes the list to the actors, configs and sessions inside it. Find a unit or actor filters the tree.
The toolbar of the list has a List | Teams switch. Teams replaces the tree and list with a map of the organization.
Lenses
The list is one of four lenses:
| Lens | Lists | Extra control |
|---|---|---|
| Actors | The Staff actors in scope | Status: All, Active, Paused, Other |
| Configs | The agent configs those actors use | Showing configs used here or Showing every config |
| Sessions | Session history for the scope, a page at a time | Footer to load more |
| Costs | Spend per config over a window | 7d, 30d, 90d. A config shared by several actors counts once |
Filter this list matches names as you type.
An actor
| Part | Content |
|---|---|
| Header | Status tag (active, paused…), a tag for how it runs (runs on a schedule, runs when called, schedule + calls), health (had failures when the last window did), the actor UUID. The toolbar has Pause and Resume; they apply at once and the toast offers undo |
| Managed by | When a repository owns the actor: the commit it came from, Change It in the Repo and Sync…. See Staff from repositories |
| Engine and where it runs | Orkestia agent (it works only through the platform's workflows) or Orkestia agent · writes code (it works in a sandboxed copy of the repository and changes go out as a branch for review). Then: Runs on (Organization default, This computer · |
| Give a task | Type a task and press Give Task (⌘↩). A session starts now and shows here and in Activity. Disabled while the actor is paused |
| Last 24 hours | Sessions, finished, failed, cost and how many wait on someone, with the platform's health reasons |
| Sessions | The actor's history. A session opens with its status, who started it (Started by), start, duration, cost, config and task, and Open in Activity |
A config page shows its model, budget per session, spend over the cost window (and how many actors share it) and Actors on this config. A unit page shows actor count, spend, charter, status, what is inside and the decisions pending for it.
This computer
Run coding agents on your own hardware instead of a hosted runner: same permissions, budget and review, on your machine. The page shows your OS and architecture and a five-step checklist:
| Step | Meaning |
|---|---|
| Linux VM support (Lima) | Needed for the agent's sandbox. Install Lima if missing; the app records when it installed it |
| Agents VM | A small Linux VM used only by coding agents. Nothing on your computer is shared with it. Start, stop and delete it here (delete removes the VM and everything in it) |
| Coding image | The image the sandbox runs. On Apple silicon an Intel image cannot run the sandbox, and the step says to use the arm64 build |
| Connected to Orkestia | A token for this computer and the runner group it joins. Disconnect stops the runner and revokes that token |
| Runner | Start and Stop. It reads Running · online · N free slots once registered |
Below the checklist, Your computers lists the bring-your-own-computer runner groups: online instances and free slots, each instance's state, whether it can code (has a coding sandbox), and a note for registrations not seen for over a day.
Coding tools on this computer lists the tools you already use (Claude Code, Codex, Cursor and others the app detects). Each uses its own sign-in on this computer; Orkestia never sees a password or token. Start asks for the folder it works in, opens a local session, and the tool asks in the app before changing files. A tool that is not installed, or needs Node.js (npx), is greyed out with the reason.
A tool can also be made an Orkestia agent: the app creates an agent config and a Staff actor for it. A task given to that actor becomes a ticket the app picks up while it runs: it runs the tool in the folder bound on this computer, comments the result on the ticket and resolves it (or blocks it). The row shows the actor, its folder (Change folder), a remove button, and an approval switch: off, the tool asks you before changing files; on, it uses the tool's own mode. Give it a task through Orkestia sends a task the way DGI would. Local sessions last while the app is open.
Staff from repositories
When a repository owns part of the staff (Staff declared as code), the actor page says Managed by it and from which commit. Sync… opens the sync sheet; Change It in the Repo opens the change on the code host. Editing the actor in the app is not how those actors change.
Coding
The list holds Connections and then every repository the connected accounts expose, with a chip for how ready each is for the coding lane.
| Chip | Meaning |
|---|---|
| Not linked | Not registered with the coding lane |
| Setup incomplete | Registered, but something is missing. The page lists the issues |
| Ready | Wired: a coding run would start |
| Blocked | Wired, but something stops it |
All | In the lane | Not linked filters the list, and Search repositories searches every connected account, not only the loaded page. A row shows delivery in flight while one is running, and the default branch. Right-click: Open, Open on GitHub, Copy Name, Copy Repository ID.
Connections
Connections lists the code-host accounts the organization can reach, with status and when each was last checked. Connect a GitHub account opens the sign-in in your browser; the page picks up the new connection when you finish. If the web console would add the connection to a different organization than this window shows, the page warns you. Other hosts are listed as coming next.
A repository
| Tab | Shows |
|---|---|
| Lane | In flight (the delivery: state, branch, who it waits on and for how long, the failure and what it needs), Waiting (N) (tickets for this lane) and Parked (N) |
| Settings | The repository's delivery settings, below |
A parked ticket carries a reason: The repository is not ready for the coding lane, Intake could not route this ticket, The coding spec is too large for one delivery, or Waiting: the repository already has a delivery in flight. Operators can return a ticket to the lane.
Operators (and above) see lane actions; the platform still decides:
| Action | Does |
|---|---|
| Attach CI log | Reads the failing CI job's log and attaches it to a blocked delivery so a repair session can see it |
| Resume | Resumes a delivery. A delivery marked not retryable resumes only with an operator override |
| Abandon | Frees the lane and keeps the evidence. The ticket stays as it is |
| Return to Lane | Clears the parking and claim labels and keeps the lane label |
Adding a repository needs the operator role. Without it the buttons say so.
Add a repository
Add a repository to the coding lane (the + in the toolbar, or Add to the coding lane… / Finish setup… on a repository) walks four steps: Repository, Check, Settings, Review. You pick the code host, the account and the repository (search finds repositories the app installation can see, not only the first page), the app reads the repository and proposes settings, you review them, and enabling runs five steps that are safe to repeat:
- Register the repository
- Link it to
- Adopt the execution profile (
orkestia.runner.json) - Activate the delivery settings
- Check a coding run would start
If a step fails, Try again picks up where it stopped. For the platform side, see Wire a repository.
Settings
Grouped, with a summary on each:
| Group | Holds |
|---|---|
| Checks & merging | Commands that must pass in the sandbox, required CI check names, Who merges (automatically or by hand) and the post-merge stages Wait for a release, Wait for a build, Wait for a deployment, each with who does it or why not |
| How work is accepted | Base branches, Work branches start with (the agent pushes to <prefix>ticket-… and never to a base branch), How many at once and Review before merge with Approvals needed |
| Where it runs | Runner group and the execution profile (from the repository, or a draft) |
| Agent | The actor and model that do the work |
| Limits | Coding attempts, Publication attempts, CI evaluations, Merge-conflict repairs, a Spending limit for this repository and Reserved per session |
A bar appears when you have unsaved changes (Save changes, Discard). Pause stops chosen operations with a reason shown to everyone; Resume undoes it. Taking a repository out of the lane can be undone from the toast, and Pushes through switches the connection used to push (a new link version, used from the next push). Settings can be restored to the earlier version when one exists.
Planning in a coding chat
A coding session is an assistant chat with a coding panel (toggle ⌘J) with four tabs: Plans, Work, Session, Runners.
New Plan
New Plan… asks for the goal ("What should change? The planner reads the code and proposes tickets.") and which repositories to plan across.
- The list shows only repositories that are ready for the lane, each with its readiness.
- Tick one or several. With none ticked the legend reads Let the planner choose the repositories; ticking shows N repositories selected, and Let the planner choose clears the selection.
- The request carries every ticked repository, and also the first one in the older single-repository field for planners that still read it. A plan may span all of them; each ticket targets one repository.
- Readiness is judged per ticket: a plan with one unready repository keeps the other tickets untouched.
Typing Plan: <goal> in the chat does the same without the form. It starts the planner linked to this conversation and sends every ready repository the goal names: a full owner/name, or the repository name (a name ending in a symbol such as c++ matches too), or the distinctive words the goal shares with a repository name. A second Plan: while one is starting or running starts nothing and says so.
Plan: replies that it is still waiting, whichever conversation asked for it. Answer it in Decisions or in the coding panel, then ask again.The plan card
| State | Meaning |
|---|---|
| Needs your review card (pending) | Expanded by default: the goal, The plan, each ticket with its repository, size, dependencies and readiness |
| Tickets created | Approved, nothing has started yet |
| In progress (blue) | At least one of the plan's tickets is moving |
| Needs you / Failed | A ticket needs a person, or one failed |
| Delivered (green) | Every ticket is terminal and none failed |
| Closed | Tickets closed without delivery. Duplicates and discarded tickets count here |
| Approved · failed to create | Approval did not create the tickets; the card says why and offers a fixed request |
The card shows a progress line and bar rolled up from the Work tab, and N tickets opens Work filtered to this plan. For a pending plan:
- Approve creates the tickets; work with no dependencies goes to the lane at once.
- Drop refuses the plan; nothing is created.
- Revise (needs a note: "What should change? (for Revise)") sends the plan back with your note. A revision keeps all the plan's repositories.
If approval would create nothing because a step is too large, the card says so in plain words and offers to ask for a plan split into smaller steps. See Decisions for the same plan in the inbox.
Work, Session and Runners
| Tab | Shows |
|---|---|
| Work | Tickets that came from plans, each with its delivery stage (Repairing, Merging, Merged, Releasing, Done, Blocked, Failed, Checks failing), pull request, checks and coding session. Finished work splits into merged, closed and failed. Actions include Open ticket, Attach CI Log, Open Repository and Return to Lane. Empty: "Approved plans become tickets here" |
| Session | The coding session started when the lane claims one of this conversation's tickets, with Inspector to open it in Activity. Empty: No coding session yet |
| Runners | The runner groups doing this conversation's work, with This chat marking its sessions. Empty: No runner is busy |
Roles matter. A person who has the chat as a viewer does not see the plan buttons. Everyone else sees them, and they are disabled with You need the operator role on the software-planner to do this until the platform confirms the operator role on the planner. While that is unknown the buttons stay enabled and the platform checks.
Workflows builder
Build, check, save, run and schedule a workflow in Orkestia Cockpit — the steps and diagram views, blocks, the Test run, versions and drafts, past runs and the assistant panel
Runners and Connections
The Run group of Orkestia Cockpit — runner groups and their instances, and the services the organization is connected to