dagron Cloud

Hosted state for teams: every CI job and engineer commits to one state, safely, and runs go through your workspace.

What it adds

Hosted state. The same document as state.json, stored for your workspace, with a compare-and-swap on every commit and a commit history.
Runs through the edge. freshet submit to your workspace, on your own compute or on dagron's workers metered in compute units.
Nothing to install. The same freshet binary; --state takes a URL instead of a file.

Set up

Get a workspace. Ask for one; you get your workspace's edge address (<your-edge> below) and API tokens.
Pick token scopes. Reading state needs any workspace token. Committing needs state:commit. Submitting runs needs runs:submit-yaml. Give CI jobs that only plan a token without either.
Point --state at the edge, with the token in FRESHET_STATE_TOKEN. The token is read only from the environment, never from a flag, so it stays out of shell history.

plan against hosted state

$ export FRESHET_STATE_TOKEN=…            # a workspace token
$ freshet plan --project models --state https://<your-edge>/state/v1
hosted state: version 7 at https://<your-edge>/state/v1
backfill plan (3 model(s), topological order):
…

Without the token, Freshet stops before any request:

missing token

$ freshet plan --project models --state https://<your-edge>/state/v1
Error: --state https://<your-edge>/state/v1 is hosted state: set FRESHET_STATE_TOKEN to an API token for the workspace (a token with the state:commit scope if this run commits)

Commit safely

Every plan against hosted state prints the version it read. Run the plan, then commit with that version: the commit lands only if nothing else committed in between.

plan → run → commit

$ freshet plan --project models --state https://<your-edge>/state/v1 --json > plan.json
hosted state: version 7 at https://<your-edge>/state/v1
# … run plan.json …
$ freshet plan --project models --state https://<your-edge>/state/v1 --commit --expect-version 7
committed state -> hosted state version 8 at https://<your-edge>/state/v1

If another job committed first, nothing is written and freshet exits 3: another commit landed after this plan was computed; re-plan. Plan again and run what is still needed. A commit that would change nothing isn't sent at all. Before the first commit, the version is none (--expect-version none).

Run through the edge

Submit to your workspace exactly as to a self-hosted dagron, with a token that has runs:submit-yaml:

submit to dagron Cloud

$ freshet submit --project models --state https://<your-edge>/state/v1 \
    --to https://<your-edge>/api/state/plans/submit \
    --header "authorization: Bearer $FRESHET_STATE_TOKEN" \
    --command 'dbt run --select {{ model }}'
submitted 3 model(s) -> run 0f0c…

Tasks run on your own runners by default, so the warehouse bill stays yours. On dagron's workers the run is metered in compute units, the same CU every plan prints; partition scoping shrinks that bill directly.

Bring an existing state.json

Hosted state stores the same document as a state file, so moving is one commit with no prior version:

import once

$ jq -n --slurpfile s state.json '{expected_version: null, snapshot: $s[0], summary: {command: "import"}}' \
    | curl -s -X POST https://<your-edge>/state/v1/commit \
        -H "authorization: Bearer $FRESHET_STATE_TOKEN" -H 'content-type: application/json' -d @-
{"version":1}

The protocol is two calls (GET /current, POST /commit); it is specified in the API reference, so any server can implement it.