Echopoint,
How Echopoint runs a Flow on three kinds of runner
Every run becomes one job with a 30-second lease. Echopoint's Cloud, on Cloudflare, gets the job pushed to it; a runner on your own instance pulls it; and your laptop or a GitHub Actions job claims its own. When a runner goes quiet, its job fails. It is never run a second time.
Twenty seconds of the mechanism. Times are shortened: a real lease lasts 30 seconds.
- You press Run. Echopoint queues one job per run.
- Cloud: Echopoint pushes the job to Cloudflare.
- Self-hosted: your server asks for work and pulls its job.
- Ephemeral: the CLI on your laptop or in CI claims its own job.
- Every runner sends heartbeats. Each one refills its job's lease.
- The server loses power. No heartbeat, so its lease runs out.
- Echopoint fails the job. It is never run a second time.
Take a Flow with two steps. The first sends POST /orders to your staging API and creates an order. The second checks that the response has status 201 and an order ID. You press Run.
Somewhere, a machine starts the Flow, sends the POST and loses power before it reads the response. The order now exists. Should Echopoint run the Flow again?
It should not, because a second run would create a second order. This note follows that one run from the button to its result, on each of the three places it can run: Echopoint's Cloud on Cloudflare, a runner on your own instance, and the CLI on your laptop or in CI. All three share one mechanism, and that mechanism is why the answer is no.
A run becomes a job
When you press Run, the API writes two records in one database transaction: the run, which the UI shows you, and a job, the unit of work a runner takes. Because they are written together, there is never a run without a job to carry it. A launch can also carry an idempotency key, so a CI step that retries its launch request gets the same run back instead of a second one.
The job starts queued. From here, only one thing differs between the three kinds of runner: who claims the job, and how it reaches them.
Echopoint API
Holds the run and its job.
- queued
- claimed, with a 30 s lease
- passed or failed
Cloud
Runs on Cloudflare, one process per job.
For a Flow your AI agent just wrote, against a public staging API. Nothing to install.
Self-hosted
A container on your own instance. Outbound requests only.
For an internal API that only your private network can reach.
Ephemeral
The CLI, on your laptop or in GitHub Actions, launches the run and runs it itself.
For smoke tests before you push, and a failing check on the pull request.
The claim and its lease
Claiming a job gives the runner a lease: the job is that runner's, and nobody else's, for the next 30 seconds. The runner keeps the lease by sending a heartbeat every 10 seconds. Each heartbeat moves the expiry forward and returns the job's status. When the API answers that a job is no longer this runner's, the runner stops that job's in-flight requests and delays.
While the Flow runs, the runner reports each step as an event with a sequence number, and the API accepts events only from the runner that holds the lease. When the Flow ends, the runner sends the result: each step's outcome, and for every assertion the expected and the actual value, passes included.
Self-hosted: your own instance pulls
Say the API you test is an internal billing service: no public address, reachable only from your VPC. A Cloud runner cannot call it, and you do not want to open a way in. This is what the self-hosted runner is for. It is a container you run on your own instance, next to the API, and it opens no port: it only makes outbound HTTPS requests to Echopoint, so it works behind a firewall that lets nothing in.
To get work, it asks for the next job, and the API holds the request open. Every 250 milliseconds the API looks for a queued job this runner can take. After 20 seconds with nothing, it answers that there is no job, and the runner asks again. A job queued while a request is open reaches the runner within about a quarter of a second, and an idle runner makes three requests a minute.
Each request says who is asking and what it can take: a stable runner ID, how many Flows it runs at once (one by default), and its capabilities, which come up again below. A runner already running as many Flows as it declared gets no new job.
There is no registration step. A runner appears in the Echopoint UI the first time it asks for work, with its current load and the time of its last heartbeat.
Cloud: pushed to Cloudflare
Cloud is the default when you do not choose a runner, and the common case: your AI agent writes a Flow through Echopoint's MCP tools and runs it against your public staging API, with nothing to install. Echopoint's Cloud runs on Cloudflare, and nothing polls here. A dispatcher inside the API claims the job and puts it on a Cloudflare Queue. A Worker takes it off the queue and hands it to a Cloudflare Container.
The queue message carries only the job's ID and a token for that one job. The container uses the token to fetch the Flow and its inputs, so secrets never travel through the queue. It then starts a new process for this job alone; that process heartbeats, reports events and sends the result with the same token, which stops working when the job ends.
The dispatcher's lease lasts 2 minutes instead of 30 seconds. A job can wait on the queue before a worker picks it up, and the worker starts heartbeating only once it has the job, so a 30-second lease could expire on a job that was about to start.
Cloud capacity is shared, so the dispatcher also decides whose job goes next. It serves organizations with the fewest Cloud jobs running first, then the one whose queued job is oldest. An organization that queues a hundred runs does not hold back another organization's single run: the extra runs wait their turn instead of being dropped.
Ephemeral: your laptop or CI claims its own
The third runner is the CLI itself, built for two places: your laptop and CI. Before you push, echopoint flow run --tag smoke runs your smoke Flows from your machine. In GitHub Actions, the same run fails the pull request when a Flow breaks:
- uses: nanostack-dev/echopoint-cli@v1
with:
api-key: ${{ secrets.ECHOPOINT_API_KEY }}
organization-id: ${{ vars.ECHOPOINT_ORGANIZATION_ID }}
tags: smoke Either way, the CLI launches the run as an ephemeral run, immediately claims its job with a one-time token, and runs the Flow inside its own process. No other runner can claim that job, and it ends when the CLI exits.
The command waits for the result and ends with an exit code your pipeline can act on:
| Exit code | Meaning |
|---|---|
| 0 | Every Flow passed |
| 1 | A Flow failed: an assertion or the runner |
| 2 | The run was cancelled |
| 3 | An API, runner or contract error |
| 4 | Timed out |
The API key it uses needs only the permission to execute Flows, plus the permission to read them when you select Flows by tag.
One engine
The three runners do not each implement Flows. The engine is one Go module, public on GitHub as echopoint-runner. The self-hosted container runs it, and the Cloud worker and the CLI import it as a library. The Cloud worker and each CLI release pin the same engine version, so a Flow runs the same code in CI as on the Cloud.
When the runner stops
Back to the order. The runner sent the POST and lost power, so its heartbeats stop. 30 seconds after the last one, the lease expires.
Echopoint does not act at that moment. A sweep runs every 15 seconds and fails each job whose lease expired more than 2 minutes earlier, with the error runner lease expired before completion
. It fails the run as well and sends the final event to anyone watching it in the UI. Try it below: choose when the power goes out and see when the run fails.
With the power lost 25 seconds in, the last heartbeat is at 20 seconds and the lease expires at 50 seconds. The 2-minute grace ends at 2 min 50 s, and the next sweep, at 3 min, fails the run.
The job is not handed to another runner. A Flow sends real requests with real effects: the order exists, and an email may have gone out. Echopoint cannot know which steps took effect before the power went, so running the Flow again could repeat them. A failed run with a clear error is the safer result, and you decide whether to run it again.
When no runner comes
A job can also wait with no runner to claim it: a self-hosted runner that is switched off, or a CI job that launched a run and died before claiming it. After 12 hours queued, the sweep fails the run with execution expired before a runner claimed it
. The wait is hours rather than minutes so that a runner offline for a working day still picks up its queued work when it comes back.
Capabilities instead of versions
Runners update on their own schedule. You pull a new self-hosted image when you choose, and your laptop or CI uses whatever CLI version is installed or pinned. A self-hosted image can be built separately from a release tag, so the binary cannot reliably report its own version. Instead, each runner sends the list of things it can do on every claim.
A Flow that marks an output as secret only goes to a runner that declares it can keep outputs secret. Any other runner gets the job failed, with an error that asks for a runner upgrade, rather than a run that might expose the value.
The list works in both directions. Earlier this month a runner release declared a capability the API did not accept yet, and the API refused that runner's claims until the API was updated. The rule we took from it: the API learns a new capability first, and runners declare it only after that.
Run it yourself
Echopoint is free while in beta; join the waitlist to get access. With an organization, you can run Flows on either of the runners you operate.
- Your own runner. Create an organization API key with the
runner:claimscope, then start the runner container withECHOPOINT_ORGANIZATION_ID,ECHOPOINT_RUNNER_API_KEYandECHOPOINT_BASE_URL=https://api.echopoint.dev. The echopoint-runner README has the image and the other settings. - Your laptop or CI. Run
echopoint flow run <flow-id>with an organization API key, or add the GitHub Actionnanostack-dev/echopoint-cli@v1shown above, which also exposes the run's status and results as step outputs.
Simplified here
- Every duration in this note (the 30-second lease, 10-second heartbeat, 20-second long poll, 15-second sweep, 2-minute grace and 12-hour expiry) is a default on 15 November 2026, read from the code. They can change.
- The Cloud queue can retry delivering a job to a worker. That is a delivery retry, not a second run of the Flow.
- Events can arrive more than once, and the API processes a repeated event as a no-op.
Sources
- echopoint-runner: the engine, the self-hosted runner, its heartbeat interval, parallel-Flow default and capability list.
- echopoint-cli:
echopoint flow run, the ephemeral claim and the exit codes. - Echopoint's API code and its Cloud worker design (not public), read on 15 November 2026: the lease, long poll, sweep, grace, 12-hour expiry, the Cloud dispatcher, and the Cloudflare Queue, Worker and Containers behind Cloud runs.