> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/docs/orchestration-quickstart.md).

# Orchestration Quickstart

This is the operator path for the shipped local Orchestration Command Center. Use it when you want to create, dispatch, review, or recover bounded local work from the cockpit.

## Start It

```bash
npm install
npm run dev
```

Open the web cockpit:

```
http://127.0.0.1:5193/
```

The dev script starts the local server on `http://127.0.0.1:2468` and the web cockpit on `http://127.0.0.1:5193`. The Orchestration panel needs the local server to be connected; if the panel says disconnected, fix the server before trying to dispatch anything.

If you use the installed CLI instead of the dev script:

```bash
npm --workspace apps/cli link
factionos start --daemon
factionos open
```

## Open The Command Center

In the cockpit, use the Orchestration card in the bottom rail. The compact card and the focused surface are two presentations of the same Command Center implementation. Click `Focus` on Orchestration, or activate the compact Orchestration panel, when you need the full working surface for Campaigns, Queue, File/Git, terminal runtime controls, and the other workbenches.

The visible focused panel is called Command Center and has these tabs:

| Tab         | Use it for                                                                           |
| ----------- | ------------------------------------------------------------------------------------ |
| Overview    | See all local command-center records and jump to related surfaces.                   |
| Campaigns   | Create campaigns, create queue entries, dispatch queue work, and inspect artifacts.  |
| Files       | Create file mutation tasks and Git tasks from reviewed drafts.                       |
| Executors   | Check terminal, Git, file, and container readiness and open terminal runtime detail. |
| Attention   | Review approval, question, blocked, and permission items.                            |
| Heroes      | Record managed local lifecycle actions when supported.                               |
| Diagnostics | Check provider/local setup readiness and create setup tasks.                         |
| Federation  | Review inbound channel/webhook commands and convert them to local tasks.             |
| Metrics     | Refresh usage/readiness and local notification posture.                              |

Use any retained `Summary` or detail popups as secondary inspectors only. The primary place to create, dispatch, recover, and review Command Center work is the focused Orchestration surface.

## Dispatch A Terminal Task

1. Open the focused `Orchestration -> Campaigns` Command Center path.
2. In `Queue workbench`, select `Terminal`.
3. Set `Queue title`.
4. Set `Command` to the command you want to run, for example `npm test`.
5. Set `Label` to a safe display label, for example `npm test`.
6. Click `Create`.
7. In the queue row that appears, click `Dispatch terminal`.
8. Use `Run` or `Terminal` on the row to inspect the scoped execution detail.

Terminal dispatch requires local PTY support. If PTY support is unavailable, the queue row should show an unavailable state instead of pretending execution worked.

## Dispatch A Git Task

1. Open the focused `Orchestration -> Campaigns` Command Center path.
2. In `Queue workbench`, select `Git`.
3. Choose `Status`, `Stage`, or `Unstage`.
4. For `Stage` or `Unstage`, enter repo-relative paths such as `apps/web/src/App.tsx`.
5. Click `Create`.
6. Click `Dispatch Git` on the queue row.

The shipped Git dispatcher only supports status, stage, and unstage. Git push, commit, branch switch, stash, revert, arbitrary Git commands, raw Git output, and diffs are intentionally not broad Command Center execution claims.

## Create A File Mutation Task

1. Open the focused `Orchestration -> Files` Command Center path.
2. Enter a repo-relative file path.
3. Choose the file operation.
4. For `edit`, provide the expected SHA-256 hash, search text, and replacement text.
5. For `write`, provide content and optionally an expected SHA-256 hash.
6. For `move`, `rename`, or `delete`, provide the expected SHA-256 hash.
7. Click `Create file task`.
8. Go back to focused `Orchestration -> Campaigns`.
9. Dispatch the created file queue row with `Dispatch file`.
10. If the result reports a backup id, use `Rollback` from the same queue row when you need to reverse it.

File dispatch is manager-owned and repo-relative. It should not show raw file contents in broad rows.

## Preview Or Dispatch Git From The File/Git Workbench

1. Open the focused `Orchestration -> Files` Command Center path.
2. In the Git workbench, choose the Git operation.
3. Enter repo-relative paths when the selected operation needs them.
4. Click `Preview` to inspect the safe plan.
5. Click `Create queue task` for queue-backed dispatch.

The workbench also contains an execute path for allowlisted local Git workbench operations, but the safer operator path is to create a queue task and dispatch from the Campaigns tab so the run is visible in the queue.

## Create And Dispatch A Campaign

1. Open the focused `Orchestration -> Campaigns` Command Center path.
2. In `Campaign workbench`, fill `Campaign`, `Task`, summaries, and expected result.
3. Click `Preview`.
4. Click `Create`.
5. In `Campaign controls`, click `Approve`.
6. If a task needs a container executable, expand its task row, enable `Use container runtime`, set the image/runtime labels, then click `Refine`.
7. Click `Dispatch executable tasks`.

Planning-only campaign tasks stay planning-only. Dispatch only runs campaign tasks that carry a validated terminal, Git, file, or container executable payload.

## Convert Inbound Channel Commands

1. Open the focused `Orchestration -> Federation` Command Center path.
2. Review channel command rows.
3. Click `Create review task` to turn an inbound command into local review work, or `Create executable task` when the row has a supported local executable conversion.
4. Dispatch the resulting queue task from the same row or from focused `Orchestration -> Campaigns`.

Inbound GitHub/generic webhooks are proposal-first. They are not trusted remote commands by default.

## API Fallback

If the UI is unclear, use the local API directly.

Create a terminal queue task:

```bash
curl -sS http://127.0.0.1:2468/task-queue \
  -H 'content-type: application/json' \
  -d '{
    "title": "Run tests",
    "summary": "Run the local test command",
    "executable": {
      "kind": "terminal",
      "commandText": "npm test",
      "commandLabel": "npm test"
    }
  }'
```

Dispatch it:

```bash
curl -sS http://127.0.0.1:2468/task-queue/<entry-id>/dispatch \
  -H 'content-type: application/json' \
  -d '{"reason":"operator dispatch"}'
```

List queue entries:

```bash
curl -sS http://127.0.0.1:2468/task-queue
```

Read command-center executions:

```bash
curl -sS http://127.0.0.1:2468/command-center/executions
```

If `FACTIONOS_AUTH_TOKEN` is set, add:

```bash
-H "authorization: Bearer $FACTIONOS_AUTH_TOKEN"
```

## What It Does Not Do

* It does not execute arbitrary remote commands.
* It does not make Worker, hosted, or chat commands trusted.
* It does not run arbitrary Docker commands or builds.
* It does not Git push.
* It does not expose raw terminal output, Git diffs, file contents, command bodies, tokens, or broad absolute paths in broad cockpit rows.

The current shipped execution families are bounded local terminal, Git status/stage/unstage, structured file mutation with rollback evidence, bounded container isolated-spawn paths, and campaign/queue dispatch for those same families.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/docs/orchestration-quickstart.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.