Local runtime providers

Choose local profiles for an application or own a local provider directly in tooling and tests.

Use @relkit/local to select local event, job, realtime, and agent-state profiles in application configuration. @relkit/providers-local contains lower-level implementations for runtime authors and tests. Creating one directly makes you responsible for its state directory and lifetime.

Read and write a local object

In a tooling or test package, install @relkit/providers-local at the version used by the application. Pass a dedicated directory to this helper:

/** Shows filesystem bucket ownership with a caller-owned directory and explicit cleanup. */
import { createLocalBucketProviderForTest } from "@relkit/providers-local";

/** Writes and reads a local object, then closes the provider without deleting its directory.
 * @param root - Dedicated directory owned by this test/application.
 * @returns The stored bytes, or undefined if an object unexpectedly disappears. */
export async function readLocalObject(root: string): Promise<Uint8Array | undefined> {
  const bucket = createLocalBucketProviderForTest({ root, maxObjectBytes: 1024 });
  try {
    if (!bucket.put || !bucket.get) throw new Error("Bucket must support reads and writes");
    await bucket.put("example.txt", new TextEncoder().encode("Hello, RELKIT!"), {
      contentType: "text/plain",
    });
    return await bucket.get("example.txt");
  } finally {
    await bucket.close();
  }
}

The result decodes to Hello, RELKIT!. The helper closes the provider after reading; closing does not delete the directory. The caller owns directory creation and removal. Local filesystem buckets do not create signed download or upload URLs. Use the S3-compatible storage setup when you need those capabilities.

Choose a capability

See the complete local provider API for options, errors, state protocols, and helper types. For ordinary function tests, prefer the smaller testing fakes.