FAQ

Choosing Chidori

Can I write agents in Python?

No — agents are TypeScript, executed by the runtime's embedded pure-Rust JavaScript engine. The Python SDK (and the TypeScript SDK) are HTTP clients for driving a running chidori serve instance from your application: create sessions, resume paused runs, deliver signals, fetch checkpoints, replay. You don't need either SDK to write or run agents.

Do I need Node.js?

No. The runtime is one Rust binary with an embedded JavaScript engine — no Node, no Deno, no V8. Even npm packages install without Node: chidori add <pkg> uses a content-addressed store with SHA-512 verification (Package Management).

Which model providers work?

Anthropic (ANTHROPIC_API_KEY), OpenAI (OPENAI_API_KEY, redirectable via OPENAI_BASE_URL), any OpenAI-compatible endpoint — DeepSeek, Groq, Ollama, vLLM, LiteLLM — via CHIDORI_OPENAI_COMPAT_URL, and a zero-setup OpenRouter fallback via chidori model-login. All can coexist; requests route by model name. Details: Providers & model selection.

How is this different from graph frameworks (LangGraph-style) or durable execution engines (Temporal-style)?

Chidori sits where the two meet. Versus graph/DSL agent frameworks: agents are plain async TypeScript — native if/for/try, real imports — not node graphs, and durability is the default rather than an add-on. Versus durable execution engines: the LLM-native primitives (prompts, tools, context, caching) are built in, replay is byte-identical with zero model calls (not a re-execution that calls the model again), and the runtime is one binary rather than a server + workers + queue. The comparison table in the README puts these side by side, and an engineering note in the repo, the AI SDK gap analysis (GitHub), is an honest feature-by-feature comparison against Vercel's AI SDK.

Where are my graphs and activity definitions?

There aren't any. Orchestration is ordinary control flow in your handler, and every await chidori.* call is already a safepoint — a host call where the run can pause, persist, and later resume (Core Concepts) — so you don't annotate steps or define activities. If you're reaching for a fan-out node, see Common Patterns for what to use instead (util.parallel, branch, actors).

I'm pointing an AI coding assistant at this. What should it read?

llm.txt — a single, complete, LLM-optimized API reference, designed to be read in full and sufficient to generate correct agents and tools without crawling the source.

Building agents

What does a replay cost?

Nothing. Replay re-executes your TypeScript, but every host call — every prompt, tool call, HTTP request — returns its recorded result from the journal. No provider is contacted and no tokens are billed. chidori verify enforces this posture (no providers, no tools, the untrusted profile) and asserts byte-identical output (Replay & Resume).

What happens if I edit my agent after recording a run?

Resume is divergence-checked: it refuses changed source rather than silently pairing recorded results with edited code; pass --allow-source-change to deliberately opt into edit-and-resume. The full divergence rules live in Replay & Resume. In CI, chidori verify fails when behavior drifts from the recording — which is exactly what makes recordings useful as tests.

Can agents use tools from MCP servers?

Yes — configure servers via CHIDORI_MCP_* and invoke their tools by name with chidori.tool(name, args), or pass the names in a prompt's tools array alongside your own defineTool handles (Host API).

Running in production

What data leaves my machine?

By default, only what your agent explicitly does: LLM calls go to the provider you configured, and fetch/tool calls go where you point them (policy-gated). Everything else is local files next to your agent: run journals under .chidori/runs/, memory under .chidori/memory/, server sessions in .chidori/sessions.sqlite3. Telemetry is opt-in — OTLP export only happens if you configure it (Observing with Tael).

How do I secure a served agent?

Set CHIDORI_API_KEY — bearer auth on everything except GET /health. It accepts a comma-separated list for zero-downtime key rotation, and SDK clients pass the same key ({ apiKey } / api_key=). Remember bare serve runs the untrusted profile — powerful effects are refused, and granting them in production is an explicit policy decision, not a flag you copy from a tutorial (CLI reference). Deployment has the full checklist, including recipes for a plain VM, Fly.io, and Kubernetes.

What is the license and supply-chain posture?

For a dependency/licence review, the facts are:

• Everything ships Apache-2.0: the workspace crates (chidori, chidori-js), the npm SDK (@1kbirds/chidori), and the PyPI SDK (chidori) all declare Apache-2.0.
• Dependency licenses are allowlisted and CI-enforced. deny.toml pins the permitted set (Apache-2.0, MIT, BSD-2/3, ISC, Zlib, BSL-1.0, Unicode-3.0, Unlicense — no copyleft), and cargo deny check runs on every PR and weekly (.github/workflows/security.yml), covering RustSec advisories, yanked crates, and license drift. A new dependency with a new license fails CI until the allowlist is extended deliberately.
• All Rust dependencies come from crates.io — git and alternate-registry sources are denied by configuration, so the tree you audit is the tree that builds.
• Generate your own inventory with cargo deny list (or cargo about) against the lockfile; the committed Cargo.lock makes the resolution reproducible.

Do sessions survive a server restart?

Yes, by default: sessions persist in SQLite next to the agent (CHIDORI_DB_PATH overrides; :memory: opts out), and chidori serve re-arms every registered detached agent at boot (Durable Storage, Detached Agents).

When things go wrong

My prompt call fails with no provider configured

Set a provider key (which ones work), run chidori model-login for the zero-setup fallback, or set CHIDORI_TEST_LLM_RESPONSE="(test reply)" to smoke-test with a static response and no network at all.

My run fails in CI but works at my terminal

chidori run asks for approval at the terminal before powerful effects and fails closed when there is no terminal to ask at — pass --trusted in scripts and CI, or configure an explicit policy (CLI reference).

My agent hangs waiting for input in a script

Under chidori run, input() reads stdin; at end-of-file it resolves to the declared default, and fails the run if there is no default rather than silently returning an empty string. Give interactive gates a default, or run the agent under chidori serve, where input() pauses the session for POST /sessions/{id}/resume.

Resume refuses to run my edited agent

That's the divergence check doing its job — see What happens if I edit my agent after recording a run?

A tool can't reach my local service

Tool fetch is SSRF-guarded: requests to localhost and private ranges are refused even under --trusted. Allow specific hosts with CHIDORI_HTTP_ALLOW_HOSTS=127.0.0.1 (comma-separated hosts, IPs, or CIDRs). Provider endpoints like CHIDORI_OPENAI_COMPAT_URL are not affected (Host API).