Local Evaluation

Prerequisites

Make sure the following are installed and available on your PATH before continuing:

• Docker (with Compose v2)
• mise, which installs the pinned Node.js, pnpm, and turbo versions
• Git

Clone the Shipfox repository to your local machine:

git clone https://github.com/ShipfoxHQ/shipfox.git
cd shipfox

Install dependencies

Install runtime tooling with mise and then install Node dependencies with pnpm:

mise install && pnpm install

mise installs the exact Node, pnpm, and turbo versions pinned in mise.toml (run mise trust if prompted). If you don't use mise, install Node, pnpm, and turbo yourself at the versions listed in that file.

Build packages

Build the packages the API and dashboard depend on. Run these two commands in order:

turbo build --filter=@shipfox/vite
turbo build --filter=@shipfox/api...

The first command builds shared UI primitives. The second builds everything the API transitively depends on. Both are incremental, so running them again after a code change only rebuilds what changed.

Start infrastructure services

Bring up the Docker Compose stack:

docker compose up -d

This starts the following services in the background:

A demo repository shipfox/demo is seeded automatically. You can connect this repository to a project for your first run without needing a real GitHub repo.

Start the API and dashboard

Open two terminal windows and start the API and dashboard processes:

# Terminal 1: API on port 16101
pnpm --filter=@shipfox/api dev

# Terminal 2: Dashboard on port 5173
pnpm --filter=@shipfox/client dev

Wait until both processes are ready before proceeding. The API prints Server listening at http://127.0.0.1:16101, and the dashboard prints VITE ready. The dashboard is available at http://localhost:5173 and the API at http://localhost:16101.

Create your account and workspace

Open http://localhost:5173 and sign up with any name, email, and password.

After verification, the dashboard walks you through setup:

1. Create your workspace: pick any name.
2. Install source control: choose Gitea and enter the organization shipfox (the org seeded by Docker Compose).
3. Configure agent provider: skip this unless you want to run agent steps immediately.
4. Create project: pick a seeded repository such as shipfox/demo. The project name is pre-filled from the repository.

Create project: pick the source integration connection and repository. The name is pre-filled.

Register a runner

A runner is required to execute jobs. Follow these steps to register one:

1. Go to Settings → Runners and click Create token. Name the token, pick an expiry, and copy the token. It is shown only once.
2. Start a runner in a third terminal, passing your token and labels as environment variables:

SHIPFOX_API_URL=http://localhost:16101 \
SHIPFOX_RUNNER_REGISTRATION_TOKEN=<YOUR_REGISTRATION_TOKEN> \
SHIPFOX_RUNNER_LABELS=ubuntu-latest,node-22 \
pnpm --filter=@shipfox/runner dev

The runner reads SHIPFOX_API_URL, SHIPFOX_RUNNER_REGISTRATION_TOKEN, and SHIPFOX_RUNNER_LABELS from its environment. Within a few seconds, its terminal prints Runner session registered and starts polling for jobs. The dashboard does not list connected runners yet, so use the runner log to confirm that it is connected.

Creating a registration token. The value is shown once, with a copy button.

Fire your first run

Create a workflow file in the shipfox/demo repository that uses a manual trigger. This is a complete workflow:

# yaml-language-server: $schema=https://www.shipfox.io/docs/workflow.schema.json
name: First run
runner: ubuntu-latest
triggers:
  on_demand:
    source: manual
    event: fire
jobs:
  hello:
    steps:
      - run: echo "Shipfox is running!"

Clone the seeded repo from the local Gitea, add the file, and push. The seeded admin account is gitea-admin / gitea-admin-dev-password, and the Gitea web UI is at http://localhost:3000:

git clone http://gitea-admin:gitea-admin-dev-password@localhost:3000/shipfox/demo.git

Shipfox picks the workflow up within seconds. Open the project's Workflows page and click Run next to the workflow. Watch the logs stream live in the run detail view.