Preview: Quoderat is in early access. This site shows the concept and direction — onboarding is manual for now.
Quoderat

Worker

The worker executes steps and reports results to the server. It runs commands, captures artifacts, and provides environmental context—but it doesn't seal envelopes.

What this page can (and cannot) claim

✓
Mechanical claims

  • • Step execution: Worker runs typed steps (command, lint, test, build, etc.) and records exit codes.
  • • Artifact production: Tool outputs become artifacts with sha256 identity.
  • • Context reporting: Worker reports environment via runner_context (OS, arch, toolchain versions).
  • • Signal relay: Worker reports progress to server; server exposes SSE to clients.

✗
No-claims

  • • No sandbox guarantees: Isolation depends on your infrastructure, not platform wording.
  • • No network blocking: Unless evidenced by recorded artifacts.
  • • No secret guarantees: Redactions are logged; leaks are not prevented.
  • • No determinism: Toolchain state is reported, not enforced.

Mental model

Worker → executes steps, produces artifacts → Server → exposes SSE, finalizes → Envelope

Worker

Runs steps, captures outputs, reports progress signals to Server.

Server

Receives signals, exposes SSE stream to clients, orchestrates finalization.

Envelope

The sealed receipt. Integrity seal is generated during finalization by the Server, not by the Worker.

Execution model

Typed steps → Artifacts → Observations discipline

  • Typed steps: Each step has a kind (command, lint, test, build, playwright, http_probe, human_approval, etc.) and records status, exit_code, and timing fields.
  • Artifact capture: stdout, stderr, reports, diffs become artifacts with sha256 + content_uri or location_hint.
  • Observations: Summaries or judgments (e.g., “tests passed”) are observations that cite basis_artifact_ids for traceability.

Runner context (reported, not guaranteed)

The envelope records facts as reported by the worker at runtime:

FieldExample
runner_context.runner_type"worker" / "ci"
runner_context.os"linux" / "darwin"
runner_context.arch"x64" / "arm64"
runner_context.toolchain.*node_version, python_version, etc.

These values are self-reported by the worker; Quoderat records them but does not independently verify.

Modes

Local / dev

Worker runs on developer machine; useful for testing before CI. Reports runner_type: "local".

CI runner

Worker runs inside GitLab/GitHub CI. Reports runner_type: "ci"; pipeline context may appear in subject.meta.

Hosted / self-hosted

Dedicated workers polling a queue; reports runner_type: "worker". You control the image and isolation.

Reliability

  • Leases & heartbeats: Worker may hold a lease on a run; if heartbeats stop, the server can mark the run as stale or reassign.
  • Retries: If a worker crashes mid-run, another worker can pick up the job (if the system supports it). Partial artifacts may be present.
  • Idempotency: Steps should be designed to tolerate re-execution; if not, document the risk.
  • Incomplete runs: If finalization never occurs, no sealed envelope is produced. The run may remain in running or stale state.

Safety & secrets

  • Logs: stdout/stderr are captured as artifacts; apply redaction policies to mask secrets.
  • Minimal env exposure: Only pass the environment variables required for execution; avoid passing full .env files.
  • Redactions as receipts: When a secret pattern is masked, a receipt is logged in redactions[]. This is proof of intervention, not a guarantee.

See Policies and Auth & Secrets for detailed guidance.

Scaling

  • Multiple workers: Workers can poll a shared queue; the server dispatches jobs and tracks ownership.
  • Dispatch / queue: Jobs enter a queue; workers claim jobs via lease. Pending jobs remain until claimed or expired.
  • Resource limits / timeouts: Configure per-job or per-step timeouts to prevent runaway execution. Exceeded limits result in step failure.

Troubleshooting

Worker not picking up jobs

Check queue connectivity and worker registration. Verify the worker is polling the correct API endpoint (see server config).

Steps timing out

Increase step timeout in job config, or optimize the step. Check for network latency or resource contention.

Missing artifacts

Verify the step produced output and that artifact capture is enabled. Check disk space and storage permissions.

runner_context fields empty

The worker may not be configured to report environment details. Check worker startup flags or environment variables.

Run stuck in “running” state

Worker may have crashed or lost connectivity. Check heartbeat logs and consider marking the run stale or reassigning.

Secrets appearing in logs

Redaction rules may not cover the pattern. Update redaction_rules and re-run. Redactions are best-effort.

Illustrative example

Illustrative only; field names and structure may vary by implementation.

{
  "execution": {
    "steps": [
      {
        "kind": "test",
        "status": "success",
        "exit_code": 0,
        "started_at": "2026-01-27T10:00:00Z",
        "finished_at": "2026-01-27T10:00:45Z",
        "stdout_artifact_id": "art-001",
        "report_artifact_ids": ["art-002"]
      },
      {
        "kind": "lint",
        "status": "success",
        "exit_code": 0,
        "started_at": "2026-01-27T10:00:46Z",
        "finished_at": "2026-01-27T10:00:52Z"
      }
    ]
  },
  "artifacts": [
    {
      "id": "art-001",
      "kind": "stdout",
      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "content_uri": "urn:sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    },
    {
      "id": "art-002",
      "kind": "junit_xml",
      "sha256": "a1b2c3d4e5f6789012345678901234567890123456789012345678901234abcd",
      "location_hint": "s3://bucket/reports/junit-2026-01-27.xml"
    }
  ],
  "observations": [
    {
      "type": "test_summary",
      "summary": "47 tests passed, 0 failed",
      "basis_artifact_ids": ["art-002"]
    }
  ],
  "runner_context": {
    "runner_type": "worker",
    "os": "linux",
    "arch": "x64",
    "toolchain": {
      "node_version": "20.11.0",
      "pnpm_version": "8.15.1"
    }
  }
}

Next steps