Skip to Content
WorldsSeeding your own

Seeding your own

Add exact rows to a twin before your test runs.

Add rows with veris sandbox data add when your test needs state the default world does not already hold. For what it does hold, see Worlds.

Finding the table and columns

Find the table and its columns before writing to them.

veris sandbox data get                              # every table, with counts
veris sandbox data schema <twin> --table customers  # columns and what they mean
veris sandbox data get <twin> customers             # what is already there

<twin> is a name from veris sandbox services list. Without --table, the schema lists the tables that twin accepts.

$CONTROL_URL is the twin’s control URL, printed by veris sandbox services get <twin>.

curl "$CONTROL_URL/veris/data"                        # every table, with counts
curl "$CONTROL_URL/veris/schema"                      # columns and what they mean
curl "$CONTROL_URL/veris/data?entity_type=customers"  # what is already there

/veris/schema describes each column in plain language, written for whoever is operating the sandbox.

Adding rows

Rows go in a file keyed by twin name, then by table:

{
  "<twin>": {
    "customers": [
      {"id": "cus_test_overdue", "email": "overdue@example.test"}
    ]
  }
}
veris sandbox data add seed.json

Each twin answers with what it added and how its counts moved:

✓ <twin>: added customers 1   (state_version 14 → 15; customers now 41)
curl -X POST "$CONTROL_URL/veris/data" \
  -H 'Content-Type: application/json' \
  -d '{
        "data": {
          "customers": [
            {"id": "cus_test_overdue", "email": "overdue@example.test"}
          ]
        }
      }'
{ "added": { "customers": 1 } }

To change or remove a row that already exists, name it by its key:

veris sandbox data set <twin> customers id=cus_test_overdue email=new@example.test
veris sandbox data delete <twin> customers id=cus_test_overdue

Each VALUE is read as JSON where it parses as JSON, so id=1 is a number and enabled=true a boolean, and kept as the literal string otherwise. delete asks before it removes; --yes answers.

Over HTTP, PATCH edits rows and DELETE removes them, with the same shape as the POST.

Everything is validated before anything is written. A wrong column name, a bad type, or a value that breaks a relationship is refused with an explanation, and your world is left untouched.

Insert order and foreign key errors

Insert the row that is referred to before the row that refers to it: a customer before their invoice, a repository before its issues. A foreign key error means that order was wrong.

File bytes are a separate step and always come last. See Files.

Ids are stable within a sandbox

Across sandboxes they are stable only when the clock is frozen.

Read them at runtime from /veris/data rather than pasting an id from a previous sandbox into a test. That is the most common cause of a suite that passed once and never again.

Letting your agent seed

Your coding agent can do all of this itself: read the schema, seed rows, arm faults. With the build and fix commands it is built in.

Resetting one twin

curl -X POST "$CONTROL_URL/veris/reset" \
  -H 'Content-Type: application/json' -d '{"profile": "default"}'

That resets one twin. To reset every twin in the sandbox together, use veris sandbox reset.

WorldsFailures and faults