@shipfox/client-runners

Docs · Getting started · Concepts · Slack community · Contributing

Build your software factory.

Shipfox is a continuous shipping platform for workflows that reason and react: every step is a shell command or an AI agent, and events drive the run from start to finish, on compute you own. A software factory that assembles itself in your repo.

name: Fix new Sentry issues
runner: ubuntu-latest
triggers:
  on_issue:
    source: sentry_acme            # a new Sentry issue starts the run
    event: issue.created
jobs:
  fix:
    steps:
      - run: npm install
      - key: fix                    # an agent step
        model: claude-opus-4-8
        prompt: >
          Sentry reported "${{ event.title }}" (${{ event.webUrl }}).
          Reproduce it in this repository, find the root cause, and fix it.
      - run: npm test               # verify the fix
        gate:
          on_failure:
            restart_from: fix        # send the agent back until the tests pass
            feedback: Unit tests are failing

If you've written GitHub Actions, you already know how to read this file, and that's deliberate. What's different is what a step can be and the control flow around it: a Sentry issue starts the run, an agent reproduces and fixes the cause, then a gate reruns the tests and sends the agent back until they pass.

Highlights

• Workflows as code. YAML under .shipfox/workflows/, versioned and reviewed like the rest of your repo. No plugin, no action, no glue.
• Trigger from your whole stack. Start runs from GitHub, Sentry, Slack, Linear, and more through integrations. Missing one? Point it at the generic webhook integration and trigger on its events too. Connect several of the same provider and target each independently.
• Automatic retry loops. Guard a step with a check (a gate): when it fails, the workflow loops back to an earlier step and tries again, up to a safe limit. That is how an agent keeps going until the tests pass, with no scripting.
• Long-running, event-driven agents. A listening job stays alive across a run and runs an agent on each new batch of events (PR review comments, new issues) until a resolution condition is met. Asynchronous agent loops, not one-shot runs.
• See the agent think. Agent steps stream structured events (messages, thinking, tool calls, token usage, and cost), not just raw text.
• Pick the agent, not just the model. Run an agent step on the pi harness (any of 30+ providers) or the claude harness (the Claude Agent SDK on your Anthropic key), chosen per step.
• Your own runners, your own keys. Runners poll outbound, so nothing connects into your network. Model traffic leaves from your runners across 30+ providers.

Core concepts

Concept	Summary
Workflow	A YAML file under .shipfox/workflows/, versioned and reviewed like code. One file, one workflow.
Trigger	What starts a run: an event from a connected integration, or an on-demand fire.
Integration	A connection to an external tool (GitHub, Sentry, Slack, Linear, ...) whose events start runs. Use the generic webhook to connect anything not built in.
Job	A group of steps on one runner. Jobs form a DAG via needs and are isolated, so each re-clones the repo.
Step	A run shell command or an agent (model + prompt, on the pi or claude harness). Runs in order within a job.
Gate	A pass/fail check on a step that retries from an earlier step when it fails. Bounded retry loops, no scripting.
Listening job	A job that waits on events and runs again per batch inside the same run, until a resolution condition. Drives event-driven, asynchronous workflows.
Runner	A process you register on your own compute; matched to jobs by label.

Getting started

Try Shipfox on your machine with the Local Evaluation guide: it runs the full stack locally, then walks you through connecting a project, registering a runner, and firing your first run. To run Shipfox for your team, see the installation docs.

Working on Shipfox itself? See CONTRIBUTING.md.

Documentation

Full documentation is published at shipfox.io/docs.

Community

• Slack: join the Shipfox community Slack for help, ideas, and release news.
• Issues: report bugs and request features on GitHub Issues.

Security

Please report vulnerabilities privately by emailing security@shipfox.io rather than opening a public issue. See SECURITY.md for details. Shipfox's token and trust model is documented in the auth security model.

Contributing

Read CONTRIBUTING.md and the codebase conventions in CLAUDE.md / AGENTS.md before opening a pull request. UI work should follow DESIGN.md; E2E work follows e2e/README.md.

License

MIT Shipfox