Jaiph Configuration

Why configuration exists

Jaiph workflows compile to Bash scripts that run agent prompts, shell commands, inbox routing, and rule checks. Configuration is how you tune the runtime (which agent backend to use, where logs go, whether the Docker sandbox is on, how inbox dispatch behaves) without changing the workflow’s control flow.

You typically set options once per project or per workflow, then rely on the same workflow source in different environments.

What you can configure (overview)

Three mechanisms apply to agent and run settings (model, backend, logs directory, debug trace, inbox parallelism):

  1. Environment variables — JAIPH_AGENT_*, JAIPH_RUNS_DIR, JAIPH_DEBUG, JAIPH_INBOX_PARALLEL, and (for Docker) JAIPH_DOCKER_*.
  2. In-file config — a config { ... } block at module (file) scope in the entry .jh file, and optionally a nested config { ... } inside a workflow { ... } body for overrides limited to that workflow.
  3. Built-in defaults — used when nothing else sets a value.

Precedence for those agent/run settings: environment → workflow-level config → module-level config → defaults. Details are in Defaults and precedence.

Docker / runtime.* keys follow the same idea (environment overrides in-file values), but they are chosen in the jaiph run driver when the process starts. They are not allowed in workflow-level config blocks, and in-file runtime.* values are not copied into JAIPH_DOCKER_* inside the Bash script for you. See Runtime keys and Inspect effective config at runtime.

In-file config (module-level)

In the entry workflow file (the path you pass to jaiph run), you can declare a single module-level config { ... } block. It is optional. If it is present:

Inside the block, each non-comment line is key = value. Empty lines and lines starting with # are ignored.

Value syntax

config {
  agent.default_model = "gpt-4"
  agent.command = "cursor-agent"
  agent.backend = "cursor"
  agent.trusted_workspace = ".jaiph/.."
  agent.cursor_flags = "--force"
  agent.claude_flags = "--model sonnet-4"
  run.logs_dir = ".jaiph/runs"
  run.debug = false
  runtime.docker_enabled = true
  runtime.docker_timeout = 300
  runtime.workspace = [
    ".:/jaiph/workspace:rw",
    "config:config:ro"
  ]
}

rule some_rule {
  true
}

workflow default {
  ensure some_rule
}

Agent keys

Run keys

Runtime keys (Docker sandbox — beta)

Docker sandboxing is in beta. See Sandboxing for mounts, workspace layout, Dockerfile detection, env forwarding, path remapping, and container behavior.

Workflow-level config

A config { ... } block may appear inside a workflow { ... } body to override module-level agent and run keys for that workflow only.

Rules:

config {
  agent.backend = "cursor"
  agent.default_model = "gpt-3.5"
}

workflow fast_check {
  config {
    agent.backend = "claude"
    agent.default_model = "gpt-4"
  }
  ensure some_rule
}

workflow default {
  # Uses module-level config (cursor / gpt-3.5).
  ensure some_rule
}

Workflow-level values apply to all steps in that workflow, including ensured rules and functions called from it. When the workflow finishes, the previous environment is restored. Other workflows in the same file are unaffected.

Precedence inside a workflow (highest wins):

  1. Environment — JAIPH_* values present when jaiph run starts win and set the corresponding *_LOCKED markers so nested run into another module cannot replace them.
  2. Workflow-level config — overrides module in-file values for the duration of that workflow; its exports also set _LOCKED so inner module-level scopes (rule/function wrappers) do not revert them.
  3. Module-level config — fills in values for workflows without their own block.
  4. Defaults — see below.

Nested run: When a workflow that has workflow-level config calls run alias.workflow in another file, the callee runs under alias::with_metadata_scope so the callee’s module config only supplies variables that are not already set (mirroring env semantics). Caller values restored when the call returns.

Backend selection

prompt steps use either the cursor backend (default) or the Claude CLI:

Backend-specific flags come from agent.cursor_flags / agent.claude_flags (or the matching env vars). There is no per-prompt backend override; the effective backend is whatever the config/env stack resolves to when the step runs. In jaiph test, mocked prompts skip real backend execution; unmocked prompts use the resolved backend.

Defaults and precedence

Built-in defaults (agent, run, runtime)

Resolution order (agent / run)

  1. Environment — JAIPH_AGENT_MODEL, JAIPH_AGENT_COMMAND, JAIPH_AGENT_BACKEND, JAIPH_AGENT_TRUSTED_WORKSPACE, JAIPH_AGENT_CURSOR_FLAGS, JAIPH_AGENT_CLAUDE_FLAGS, JAIPH_RUNS_DIR, JAIPH_DEBUG, JAIPH_INBOX_PARALLEL. When set here, values override in-file config for the entire jaiph run process and lock against replacement on nested run (see Config to env mapping).
  2. Workflow-level config — for steps inside that workflow; locks its overrides as described above.
  3. Module-level config — from the entry file, or from the current module after run other.default establishes that module’s scope.
  4. Built-in defaults — as listed.

Docker / runtime.* (driver-only)

For runtime.*, the jaiph run driver merges JAIPH_DOCKER_* environment → module-level in-file runtime.* → defaults (mounts are not taken from env). Workflow-level config cannot set these. Invalid or unparsable JAIPH_DOCKER_TIMEOUT falls back to the default timeout.

Config to env mapping

In-file key Environment variable
agent.default_model JAIPH_AGENT_MODEL
agent.command JAIPH_AGENT_COMMAND
agent.backend JAIPH_AGENT_BACKEND
agent.trusted_workspace JAIPH_AGENT_TRUSTED_WORKSPACE
agent.cursor_flags JAIPH_AGENT_CURSOR_FLAGS
agent.claude_flags JAIPH_AGENT_CLAUDE_FLAGS
run.logs_dir JAIPH_RUNS_DIR
run.debug JAIPH_DEBUG
run.inbox_parallel JAIPH_INBOX_PARALLEL
runtime.docker_enabled JAIPH_DOCKER_ENABLED
runtime.docker_image JAIPH_DOCKER_IMAGE
runtime.docker_network JAIPH_DOCKER_NETWORK
runtime.docker_timeout JAIPH_DOCKER_TIMEOUT
runtime.workspace (no env override)

Inspect effective config at runtime

Inside workflows, rules, and functions, agent and run settings are visible as the usual JAIPH_* variables, for example JAIPH_AGENT_BACKEND, JAIPH_AGENT_MODEL, JAIPH_RUNS_DIR, JAIPH_DEBUG, and JAIPH_INBOX_PARALLEL.

workflow default {
  printf 'backend=%s\n' "$JAIPH_AGENT_BACKEND" >> ".jaiph/meta-debug.log"
  printf 'trusted_workspace=%s\n' "$JAIPH_AGENT_TRUSTED_WORKSPACE" >> ".jaiph/meta-debug.log"
}

JAIPH_DOCKER_* is not populated from in-file runtime.* inside the Bash process. Those variables only affect the run if they are already present in the environment that launches jaiph run (or if your script exports them itself).

When a workflow calls another module via run alias.default, the callee runs under that module’s metadata scope; unset variables are filled from the callee’s module config. When the call returns, the caller’s values are restored.

Created by jaiph init

jaiph init creates .jaiph/bootstrap.jh and syncs .jaiph/jaiph-skill.md from your installation. It does not add a separate config file; use config { ... } in your workflow sources.

© 2026 Jaiph — Open Source · Powerful · Friendly!