Skip to content
grafOS docs

local-dev

The fastest inner loop for grafOS development. grafos dev up stands up a real mTLS+token stack on loopback — one fabricbiosd + one grafos-scheduler — rooted in .grafos/dev/ under the current project. You build, validate, run, and tear down without ever touching a cloud cell. The same tasklet you’d ship to aws or gcp runs against the local stack with no source changes; only the scheduler URL differs.

Source

cookbook/local-dev/ in the source tree.

The Rust side is intentionally tiny — a pure compute() that returns a JSON document tagged with the environment it ran in. The value of this recipe is the workflow, not the code.

pub fn compute(input: &[u8]) -> LocalDevOutput {
    LocalDevOutput {
        ran_in: "local-dev".to_string(),
        input_bytes: input.len(),
    }
}

What grafos dev up does

  1. Issues a fresh CA + server cert + tenant cert under .grafos/dev/trust/. Every dev up rotates them; no shared dev CA leaks between projects.
  2. Spawns fabricbiosd control-server on a loopback QUIC port, advertising a tiny memory pool (default 128 KiB; bump with --mem-capacity 16m for larger leases).
  3. Spawns grafos-scheduler --mode cell with --auth-mode mtls+token. Local runs pay the same auth tax as cloud runs — that’s the point.
  4. Promotes the scheduler and registers your tenant. The tenant name comes from your account credentials when you’re signed in (your email’s safe form) and falls back to dev-tenant otherwise.
  5. Starts the loopback “Run locally” helper. The dashboard’s Developer tab pastes the URL + bearer once; localStorage remembers them until dev down.

State persists in .grafos/dev/dev.json. PIDs and logs sit alongside it. grafos dev doctor re-reads that file and probes the scheduler’s /health and tenant listing — scripts can grep its output for fitness.

The inner loop

Terminal window
grafos dev up                            # ~3 seconds, then idle
grafos tasklet build                     # rebuild your wasm
grafos validate                          # static checks, no network
grafos deploy run --provider local \
    --tasklet local-dev --mem 32768 --json
# inspect artifacts, edit code, re-run
grafos dev down                          # SIGTERM both daemons, leave logs

The --provider local flag points the deploy at dev.json’s scheduler URL with the issued tenant cert. No env vars to set, no cloud spend, no cell allocator queue.

When to use local-dev

  • Tight iteration on tasklet logic. Edit, rebuild, redeploy in seconds with no cloud round-trip.
  • Reproducing a failure offline. A bug that surfaced on a cloud cell often reproduces against local-dev with the same input artifacts. grafos artifacts <run-id> --download plus grafos deploy run --provider local --input <file> is the diagnostic loop.
  • CI integration tests. Spin up a local fabric inside the test harness, deploy a recipe, assert the output, tear down. No credentials beyond grafos dev up.

When to deploy to a cloud cell instead

  • Hardware-specific behaviour. GPU tasklets, NVMe leases, RDMA — the local fabric advertises a CPU + memory pool only. A real GPU lease needs a cell with a real GPU.
  • Multi-tenant contention testing. Local-dev is single-tenant by construction. Quota enforcement, fair-share scheduling, and admission-control behaviour need a cloud cell with other tenants present.
  • Performance numbers you’ll quote. Local-dev runs share your laptop’s L3 cache with everything else; latencies aren’t representative.

Production drop-in

The same tasklet binary deploys to a cloud cell by changing one flag:

Terminal window
grafos deploy run --provider local --tasklet local-dev --mem 32768
grafos deploy run --provider aws   --tasklet local-dev --mem 32768

The compute() function, the wasm artifact, the JSON wire shape — all identical. The scheduler URL, the tenant cert, and the cell that lands the run are the only moving parts. That’s the contract: develop locally with full mTLS+token semantics, ship to a cloud cell when the workload demands real hardware.