Getting started

Run a checked-in plan against a disposable sample API, then write a small plan for a service you control. Commands below use a POSIX shell from the repository root. The supported walkthrough baseline is Linux (including a Linux environment on Windows); native Windows and macOS execution are not established here.

Prerequisites

Obtain a source checkout or archive containing go.mod, cmd/, and examples/. This guide does not assume a particular source-host URL or a published binary installer. Building requires Go 1.26 (the repository prefers toolchain 1.26.7) and network access to download modules and, if needed, the Go toolchain. A running HTTP plan does not require Go. No Nix, Kubernetes cluster, database, Node, or Python is needed for this first run.

Build from source

From the checkout root:

CGO_ENABLED=0 go build -o bin/ ./cmd/...

make build is an equivalent convenience if Make is installed. The commands in this guide use bin/vero; reference pages use vero to mean a binary already on your PATH.

Run the sample API

Use two terminals at the checkout root. In Terminal 1, start the disposable fixture in the foreground:

bin/vero-testserver

Leave it running. In Terminal 2, inspect the graph and run the rate-limit example:

bin/vero plan --graph examples/rate-limit.yaml
bin/vero run examples/rate-limit.yaml

The graph shows task data dependencies and shared-resource claims. With the fixture running on its default port 18080, the run should report four passed tasks and exit 0; elapsed time varies. Stop the fixture with Ctrl-C in Terminal 1 when finished. vero-testserver is a demonstration API, not a daemon required to test your own service. The rate-limit example assumes its authentication, reset, and orders endpoints; changing only the URL does not adapt that plan to an arbitrary API. For requirements of the other checked-in plans, see Running the examples.

Test your own service

Save this complete read-only plan as health.yaml in the checkout root:

apiVersion: vero.plan/v1
kind: Plan
metadata: { name: service-health }
env:
  baseUrl: "${VERO_BASE_URL}"
  healthPath: "${VERO_HEALTH_PATH:-/healthz}"
lifecycle: { strategy: isolated }
tasks:
  - name: health
    steps:
      - http:
          method: GET
          url: "{{ env.baseUrl }}{{ env.healthPath }}"
        assert: [status == 200]

Against the sample API, in Terminal 2:

export VERO_BASE_URL=http://127.0.0.1:18080
bin/vero plan health.yaml
bin/vero run health.yaml

Expect one passed task and exit 0. For another dedicated test API, set VERO_BASE_URL to its origin without a trailing slash and VERO_HEALTH_PATH to its health endpoint starting with /. Adjust the expected status to the service's documented contract, not just to turn a failure green. The required base URL has no default: an unset target fails at load time before any request. Neither variable is secret; use secretRef for real credentials.

isolated declares an isolation assumption; it does not start a server. Use a dedicated test target. For plans that mutate application data, select a real reset strategy or uniquely named data rather than copying this declaration without isolation. The plan reference describes lifecycle strategies and assertions.

Troubleshooting

• bin/vero: not found: build from source first, from the checkout root.
• Connection refused: start the sample fixture in Terminal 1, or verify your own service is listening at the configured URL.
• Port 18080 occupied: stop only your own fixture, or choose another address and change the plan target too. The shipped rate-limit plan hardcodes port 18080; it does not use VERO_BASE_URL.
• Required environment variable unset: vero plan exits with a load error before making a request. Set VERO_BASE_URL for health.yaml, or provide the variable named in your plan.
• Assertion failed: inspect the actual status and response against your service's contract. Do not weaken an assertion automatically to make the run pass.