Documentation

Generating a key

Keys are generated via the admin API. You need the ADMIN_TOKEN to create one.

# Generate a key for your domain
$ curl -X POST https://warppool.tech/api/admin/keys \
    -H "Authorization: Bearer $ADMIN_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"site": "example.com"}'

> { "key": "a1b2c3d4e5f6...",
    "site": "example.com",
    "created_at": "2026-06-15T10:00:00" }

# List all keys (values redacted)
$ curl https://warppool.tech/api/admin/keys \
    -H "Authorization: Bearer $ADMIN_TOKEN"

Using the key

Add the key as an api-key attribute on the embed script tag. The loader script (w.js) reads it and passes it to the iframe.

<script
  src="https://warppool.tech/w.js"
  api-key="a1b2c3d4e5f6..."
  async
></script>

Origin validation

On each WebSocket connection, the coordinator checks that the request origin matches the domain registered to the key. Subdomains are supported: www.example.com matches a key registered to example.com. Requests from non-matching origins are rejected.

What you provide

1. The WGSL kernel.

   A compute shader that reads chunk parameters from a uniform buffer and writes output to a storage buffer. If you've written a CUDA kernel, the mental model is identical; the syntax is closer to Rust.

2. The chunk manifest.

   A JSON document describing how the job splits into chunks — one parameter set per chunk. The coordinator hands one entry to each worker.

3. The reducer.

   How to combine per-chunk results into a single answer. Built-ins: sum, concat, max, min, argmax, topk. Or supply a second WGSL kernel for custom reductions.

4. The redundancy policy.

   Default k=2 with a third opinion on disagreement. Higher k for safety-critical runs; k=1 for cheap exploratory sweeps.

5. An optional deadline.

   Without a deadline the coordinator picks the cheapest workers. Add one to recruit faster nodes and finish by a wall-clock target.

End-to-end example: Monte Carlo π

@group(0) @binding(0) var<uniform> params: Params;
@group(0) @binding(1) var<storage, read_write> hits: atomic<u32>;

struct Params {
  seed_start:         u32,
  num_samples:        u32,
  samples_per_thread: u32,
}

// PCG hash — fast, good statistical properties
fn pcg(x: u32) -> u32 {
  var s = x * 747796405u + 2891336453u;
  var w = ((s >> ((s >> 28u) + 4u)) ^ s) * 277803737u;
  return (w >> 22u) ^ w;
}

@compute @workgroup_size(256)
fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
  let tid = gid.x;
  var state = pcg(pcg(params.seed_start + tid));
  var local_hits: u32 = 0u;
  for (var i: u32 = 0u; i < params.samples_per_thread; i++) {
    state = pcg(state);
    let x = f32(state) / 4294967296.0;
    state = pcg(state);
    let y = f32(state) / 4294967296.0;
    if (x*x + y*y < 1.0) { local_hits += 1u; }
  }
  atomicAdd(&hits, local_hits);
}

# 1. Upload the kernel
$ curl https://warppool.tech/api/kernels \
    -F "src=@monte_carlo_pi.wgsl"
> { "kernel_id": "wgsl-pi-7f3" }

# 2. Build a chunk manifest — 100 chunks of
# 100M samples each, distinct seed ranges
$ python -c "
import json
print(json.dumps({
  'chunks': [
    {'seed_start': i * (1<<24),
     'num_samples': 100_000_000,
     'samples_per_thread': 256}
    for i in range(100)
  ],
}))" > manifest.json

# 3. Submit the job
$ curl https://warppool.tech/api/jobs \
    -H "Authorization: Bearer $WARPPOOL_TOKEN" \
    -F "kernel_id=wgsl-pi-7f3" \
    -F "manifest=@manifest.json" \
    -F "reducer=sum" \
    -F "redundancy=2"
> { "job_id": "job-9a2c",
    "queued_at": "2026-05-27T14:02:11Z",
    "chunks": 100, "est_seconds": 38 }

# 4. Stream results back
$ curl https://warppool.tech/api/jobs/job-9a2c/stream
event: chunk_done
data: {"chunk":0,"hits":78539701}
event: chunk_done
data: {"chunk":1,"hits":78540234}
...
event: job_done
data: {"pi":3.14159265}

Pricing

$ pip install py2wgsl        # zero runtime dependencies
$ pip install "py2wgsl[gpu]"   # + wgpu, to run kernels from Python

from py2wgsl import (
    Array, f32, compile_kernel,
    global_id, array_length,
)

# Each scalar param becomes a uniform field;
# each Array becomes a storage buffer.
def scale_add(
    scale: f32, offset: f32,
    values: Array[f32], result: Array[f32],
):
    i = global_id()
    if i < array_length(result):
        result[i] = values[i] * scale + offset

kernel = compile_kernel(scale_add, workgroup_size=64)

# The complete WGSL module — feed straight
# to device.createShaderModule()
>>> print(kernel.wgsl)
@group(0) @binding(0) var<uniform> params: Params;
@group(0) @binding(1) var<storage, read> values: ...
@group(0) @binding(2) var<storage, read_write> result: ...
@compute @workgroup_size(64)
fn main(...) { ... }

# Binding layout metadata for your bind group
>>> kernel.buffers
[UniformField('scale', ...), BufferBinding('result', read_write=True), ...]

Parameter → binding mapping

Parameters map to bindings by their type annotation, in declaration order. Buffers the kernel writes to get read_write access; the rest are read. The entry point is always fn main with @builtin(global_invocation_id).

f32, i32, u32

A field in the Params uniform struct at @binding(0). (float/int also accepted.)

Array[f32 | i32 | u32]

A storage buffer at the next binding, in declaration order.

1. Register your public key.

   Open the SSH Access tab on your dashboard, give the key a name, and paste the contents of your public key file (e.g. ~/.ssh/id_ed25519.pub). Accepted types: ssh-ed25519, ssh-rsa, and ecdsa-sha2-nistp256/384/521. Keys are identified by their SHA256: fingerprint and can be revoked any time. Only public keys are stored — private key material never touches the server.

2. Find your gateway login.

   Each account gets a stable gateway username of the form wp-<8 chars>, shown in the SSH Access tab alongside the host. Connect with your registered key:

   terminal

   $ ssh wp-3f9a2c1b@ssh.warppool.tech

3. Submit with the warp CLI.

   Run warp submit over the connection — inline as a one-shot command, or interactively once you're on the gateway.

   terminal

   # One-shot: submit a Monte Carlo pi job
   $ ssh wp-3f9a2c1b@ssh.warppool.tech \
         warp submit --samples 100000000 --name my-job
   
   # Or bring your own compiled kernel + manifest
   $ warp submit --kernel kernel.wgsl \
         --manifest manifest.json --reducer sum
   
   > job-9a2c queued · 100 chunks · est 38s

4. Fetch your results.

   Job products land under jobs/<job-id>/ on the gateway. Pull them down with scp once the run completes:

   terminal

   $ scp wp-3f9a2c1b@ssh.warppool.tech:jobs/job-9a2c/output.json .

Redundant dispatch

Every chunk goes to 2–3 independent workers. Results are compared within numeric tolerance. Disagreement triggers re-runs on disjoint nodes; persistent disagreement quarantines the kernel for human review.

Canary chunks

A fraction of dispatched chunks have known answers seeded by the coordinator. Workers don't know which. Returning the wrong answer to a canary downranks the worker silently.

Browser sandbox

Workers run inside the browser's own GPU sandbox. No filesystem access, no native APIs, no persistent state across reloads. Bounded memory per chunk. Visitor closes the tab — the worker is gone.

Per-job audit trail

Every dispatch and result for your job is appended to a log keyed by worker ID and chunk hash. You can replay it, verify the reduction, and check that no worker's output was silently dropped.