# How Shipfox works (https://www.shipfox.io/docs/understand)

Description: See how an event becomes visible work and how that work can repeat or wait.

Shipfox stores engineering work as **workflows** beside the code they act on.
An event starts a run. Jobs divide the work. Runners provide the compute, and
steps perform fixed commands or work that needs an agent's judgment.

Shipfox plans and records the work. Runners execute it in an isolated
environment. Every Shipfox Cloud workspace can use Shipfox-hosted runners.
Teams can also connect self-managed runners for environments they control.

The same model appears in the workflow file and in the run view.

Start with the core path. Add agents or waiting only when the task needs them.

## The lifecycle at a glance [#the-lifecycle-at-a-glance]

```text
event -> trigger -> run snapshot
                       |
                       +-> job -> runner -> ordered steps -> result
                       |
                       `-> later event -> listening-job execution
```

A run uses a workflow snapshot. A later edit cannot change active work. Each
job gets its own checkout. Steps share that checkout and run in order.

Most runs follow the direct path from event to result. Shipfox adds two forms of
controlled repetition.

* A **feedback loop** sends work back when an objective check fails.
* A **listening job** keeps the run open for related events that arrive later.

These forms solve different problems. A failed check means the current attempt
needs more work. A later review comment means the same run has received new
input.

## Follow the core path [#follow-the-core-path]

Read these pages in order when the model is new.

1. [Workspaces and projects](https://www.shipfox.io/docs/understand/workspaces-and-projects) explains what
   a team shares and what stays tied to one repository.
2. [Workflows and runs](https://www.shipfox.io/docs/understand/workflows-and-runs) separates the stored
   definition from each recorded use and its attempts.
3. [Events and triggers](https://www.shipfox.io/docs/understand/events-and-triggers) explains why signals
   and run-creation policy remain separate.
4. [Jobs and steps](https://www.shipfox.io/docs/understand/jobs-and-steps) explains how to choose a work
   boundary and what that boundary isolates.
5. [Runners and execution
   environments](https://www.shipfox.io/docs/understand/runners-and-execution-environments) explains how
   hosted and self-managed capacity place each job.
6. [Context and templating](https://www.shipfox.io/docs/understand/data-and-templating) explains when data
   becomes available and how results move forward.
7. [Integrations, integration connections, and
   tools](https://www.shipfox.io/docs/understand/integrations-connections-and-tools) explains how events,
   checkout access, and external tools cross workspace boundaries.

## Add judgment and repetition [#add-judgment-and-repetition]

These pages build on the core path.

* [Agents](https://www.shipfox.io/docs/understand/agents) helps choose between a fixed command and work
  that needs judgment.
* [Agent sessions](https://www.shipfox.io/docs/understand/agent-sessions) explains how a later agent step
  continues an earlier agent's conversation without sharing its files.
* [Feedback loops](https://www.shipfox.io/docs/understand/feedback-loops) explains why an independent
  check, not agent confidence, should decide whether work repeats.
* [Listening jobs](https://www.shipfox.io/docs/understand/listening-jobs) explains how later events
  continue the same run without becoming retries or new runs.

The dashboard mirrors this model. It keeps the run, its attempts, job
executions, step attempts, logs, outputs, and final status together. That shape
lets a reader see both what the workflow planned and what actually happened.

### [Run your first workflow](https://www.shipfox.io/docs/getting-started)

Use a guided project to see the model in a working run.