Local development

Vadyl runs identically locally and in production — same canonical runtime, same compiled APIs, same lifecycle. Local development gives you an isolated sandbox database and a hot-reload loop on your product model and code without touching the cloud.

Start the dev server

vadyl dev

This boots a local Vadyl runtime on http://localhost:7213, provisions an embedded SQLite or Postgres instance (your choice viavadyl.config.ts), applies your schema, and watches your source files for changes. Edits to entities, policies, workflows, connections, or handlers reload in under a second.

Connect to managed providers locally

For closer-to-production fidelity, point local development at managed provider instances:

// vadyl.config.ts
export default {
  bindings: {
    primary: { type: "postgres", url: process.env.DEV_DATABASE_URL },
    cache:   { type: "redis", url: process.env.DEV_REDIS_URL },
    storage: { type: "s3", bucket: "my-app-dev" },
  },
};

The capability-surface compiler picks up your bindings and resolves every operation through them — same code path as production.

Sandboxes — disposable databases per branch

Each Vadyl branch can spin up an isolated sandbox database with its own DDL applied, optionally pre-seeded from a snapshot. Sandboxes are the unit you test risky migrations against:

vadyl branch create feature/orders-refund
vadyl sandbox create --branch feature/orders-refund --seed snapshot:latest
vadyl sandbox apply  # runs the branch's DDL

See Branching for the full model.

The coding workspace

Open http://localhost:7213/workspace for the in-browser IDE — file tree, Monaco editor with full type completion against the compiled contract projection, execution surface inspector, runtime unit dialog, publication lineage pane. The workspace is a peer consumer of the canonical APIs, not a privileged tool. Anything you can do in the workspace, you can do via the CLI or SDK.

Hot reload semantics

Vadyl distinguishes two kinds of edit:

• Authored code edits (handlers, workflows, custom logic) hot-reload immediately. The new code runs on the next request.
• Schema edits (entities, fields, relations) are classified and applied through the schema-transition pipeline. Safe additive changes apply instantly; destructive or backfill-requiring changes prompt for explicit approval.

Inspecting state

vadyl entities list
vadyl entities show Order --include relations
vadyl runs list                  # operational task runs
vadyl events tail                # canonical platform event stream
vadyl explain read --entity Order --filter "status=paid"

The explainability planeshows you exactly how Vadyl resolved a query, including the AST plan, the access-engine decision, the cache decision, and which provider executed the operation.