---
title: Runtime Configuration reference
description: Look up the createVectorBuilder() runtimeConfig option, file paths, precedence, schema output, slug constraints, and failure behavior.
sidebar:
  label: Runtime config
---

A builder opts into per-installation Runtime Configuration with the `runtimeConfig` option.

```ts title="src/opencode.ts"
import { createVectorBuilder } from '@evilkiwi/vector';
import * as z from 'zod';

const RuntimeConfig = z.object({
  audience: z.string().default('the team'),
});

const vector = createVectorBuilder({
  runtimeConfig: {
    slug: 'project-tools',
    schema: RuntimeConfig,
  },
});

export default vector.defineVector({
  id: 'project-tools',
  build: (context) => {
    context.runtimeConfig.audience;

    return {};
  },
});
```

## Definition fields

| Field    | Type                        | Required | Meaning                                                                 |
| -------- | --------------------------- | -------- | ----------------------------------------------------------------------- |
| `slug`   | `string`                    | Yes      | Safe basename shared by global and project Runtime Configuration files. |
| `schema` | Standard Schema V1 instance | Yes      | Validates the merged JSON and determines `context.runtimeConfig`.       |

Vector accepts any Standard Schema V1 implementation. Schema defaults and transformations become the `context.runtimeConfig` value and type. Vector does not generate a fixed Runtime Configuration schema.

## Paths and precedence

For the slug `project-tools`, Vector reads these files in order:

1. `$XDG_CONFIG_HOME/opencode/project-tools.json`, or `~/.config/opencode/project-tools.json` when `XDG_CONFIG_HOME` is unset or empty.
2. `<cwd>/.opencode/project-tools.json`.

A missing file contributes an empty object. Global and project plain objects merge recursively. Project values take precedence. Arrays, scalars, `null`, and type changes replace the global value. Vector validates the merged value once and passes the schema output unchanged to every build callback.

When `createVectorBuilder()` receives no `runtimeConfig`, Vector skips both files and supplies a fresh mutable empty object through `context.runtimeConfig` for each activation.

## Slug constraints

The slug uses lowercase ASCII letters and digits separated by single hyphens. It cannot begin or end with a hyphen, contain repeated hyphens, or equal a Windows reserved device name such as `con`, `prn`, `aux`, `nul`, `com1` through `com9`, or `lpt1` through `lpt9`. An invalid slug throws synchronously when the builder is created.

## Failures

Read, JSON parse, and schema errors name the affected source and path without including raw Runtime Configuration contents. Correct the named file, schema, or value, then reload OpenCode. Vector does not watch either Runtime Configuration file.

Use [Add Runtime Configuration](/build/runtime-config) for a complete task. See [Context](/api/context) for callback types.