Configure

Set up from any MCP client

Any MCP client connected to Horde’s unbound administrative horde mcp bridge can be the parent agent. Ask it to inspect setup with your repository path; Horde reports repository registration, child executor roles, provider authentication, controller state, and Link wallet readiness. The parent connection does not choose the child workers’ models.

The agent can assign a configured provider to roles such as planner, worker, and reviewer with agent_setup action configure_workers, even before billing is complete. It uses provider_wallet, provider_signup, and provider_topup for Tuara funding. Tell the agent your spending limits and terms decision in ordinary language; you do not need to write JSON.

A local MCP client can launch Horde over stdio. A remote client needs a reachable, authenticated transport, and installing Horde does not register a connector in that client automatically. Codex and Claude can also use horde init for repository instructions and their client-specific MCP configuration.

Settings files

Run horde config to print starter TOML. User settings live in ~/.config/horde/config.toml, or $XDG_CONFIG_HOME/horde/config.toml. A repository can override workflow settings in .horde/horde.toml. The legacy .horde.toml also loads; the nested file wins when both set the same value.

Horde reads these settings when you submit a task. Later edits apply to new tasks.

These user settings apply to the default project. For a named project, follow project configuration and provider accounts; each project needs its own configuration and access grants.

concurrency = 4
autonomy = true
timeout_seconds = 1800

[executors.worker]
provider = "codex"

[executors.reviewer]
provider = "claude"

Codex and Claude roles use the installed CLI and its existing login by default. Configure and authenticate each execution host separately. Set autonomy = false to require an initial confirmation before work starts.

Model protocols and when to use them

Horde uses generative models to carry out coding steps and decision models to answer bounded questions about the work. Choose a provider with the protocol your executor supports:

Here, “completions” means Chat Completions. Horde has no adapter for the legacy text /completions endpoint. The native executor uses Chat Completions; Responses and Messages run through their respective CLI harnesses. A decision request has no coding tools and does not replace a worker.

Native coding through Tuara

Define the endpoint and credential source on a provider, then assign that provider to a role. Select a generative model from the provider’s catalog:

[providers.tuara]
kind = "tuara"
auth_mode = "api"
base_url = "https://tuara.com/router/v1"
api_key_env = "TUARA_API_KEY"
model = "your-generative-model-id"
stream = true

[executors.worker]
provider = "tuara"

Horde appends /chat/completions to this base URL. A local compatible server can use http://127.0.0.1:8122/v1 instead. With model = "auto", Horde selects the sole model in /models; a catalog with multiple models requires an explicit ID.

horde config models tuara
horde doctor --provider tuara
horde doctor --probe --provider tuara

The probe makes a model request to check streamed tool calls and consumes provider capacity.

Responses through Codex

[providers.openai]
kind = "codex"
auth_mode = "api"
base_url = "https://api.openai.com/v1"
api_key_env = "OPENAI_API_KEY"

[executors.worker]
provider = "openai"

Horde configures the Codex harness to use Responses. For Messages through Claude, use a provider with kind = "claude", auth_mode = "api", the Anthropic-compatible base URL, and its key variable. The built-in codex and claude providers continue to use subscription login.

Jev decisions through Tuara

Decision requests are disabled by default. Add this separately to your user configuration to record routing advice and work-product reviews while your coding workers continue to execute steps:

[decision]
mode = "shadow"
backend = "tuara"
base_url = "https://tuara.com/router"
api_key_env = "TUARA_API_KEY"
model = "XXXXTSJV130XXX"
protocol = "systemone-v1"
review_enabled = true
deadline_ms = 30000

[[decision.capability_guidance]]
runtime = "local"
capability = "worker"
description = "Use for repository changes assigned to the worker role."

Horde appends /v1/systemone to the decision base URL, which ends at /router. The example uses Jev’s Tuara catalog ID. Both the coding provider and decision provider can reference TUARA_API_KEY, but their endpoints and models are configured separately.

Give each eligible runtime and role its own capability_guidance entry. Horde considers only available candidates already allowed by the task’s execution policy; missing guidance produces an abstention. Repository settings cannot enable or change decisions.

In shadow mode, routing and review results are advisory. They do not select a different executor or authorize a merge. Inspect requests, abstentions, and outcomes with horde decisions TASK_ID, and work-product reviews with horde reviews TASK_ID. The horde metrics TASK_ID command includes decision usage and latency.

Native context pruning and browser testing are separate opt-ins through native_context_mode and browser_test_mode. Each defaults to "disabled"; "shadow" records proposals, while "active" applies bounded actions within Horde’s checks. These features require decision.mode = "shadow" and do not rewrite external Codex or Claude sessions. Automatic delivery has a separate policy and requires an enrolled qualification. Qualification enrollment is not yet supported, so the live Jev smoke test does not enable autonomous merges.

Concurrency

horde config get concurrency
horde config set concurrency 8
horde runtime drain
horde runtime resume

Each runtime has its own persistent ceiling, from 1 to 64 workers. The default is four. Lowering the ceiling lets active work finish. Draining stops new invocations until you resume.

Account usage

horde usage

Usage reports show available capacity observations, their source, and freshness. Missing quota data stays unknown. Subscription percentages are not inferred from token counts.

Capacity policy lives in ~/.config/horde/runtimes.toml:

[capacity_policy]
warn_percent = 80
switch_percent = 90
stale_seconds = 300

At the switch threshold, Horde follows your configured fallback chain. If every configured option is unavailable, work waits. For example, add this to config.toml to fall back from the worker role to the default Claude role:

[fallbacks]
worker = "claude"

Credentials

For API-backed executors, configure kind, auth_mode = "api", base_url, and api_key_env on the provider. Each role selects it with provider = "name". Set the named key in the daemon environment before starting it. Boot services also read a private credentials.env beside config.toml; set that file’s permissions to 0600.

Keep credentials out of repository settings. Pairing a remote does not copy your subscription login or provider keys.

For an existing Tuara account, import its inference key with horde config provider add tuara, or ask your connected agent to use provider_login. That flow guides you to Tuara’s key page, verifies the key you supply, and saves it.

Create a funded Tuara account

Horde can create a Tuara organization, fund it through Stripe’s Link wallet, and save its new inference key privately. Signup uses Tuara’s Machine Payments Protocol endpoint. You do not need to copy the new key or write operation JSON.

For a Tuara test-mode account, pass --test-mode to signup or ask your MCP agent to use test_mode: true. You approve Horde with a regular Link account; Link supplies test payment credentials without charging its underlying payment method. Horde saves this choice with the signup request, so a resumed request stays in test mode.

Your connected agent first inspects the private Link wallet connection. If Link is missing, Horde uses the host’s Node.js and npm to install a pinned Link CLI under its configuration directory. If either prerequisite is missing, the agent receives a clear setup action. After installation succeeds, it starts device login and relays Link’s verification URL and phrase. The agent checks the session until it finishes and reads safe wallet readiness before starting signup.

Link keeps payment methods in its hosted wallet. When Horde reports a missing payment method or verification requirement, open that wallet and complete the action there. Link’s agent wallet currently supports US accounts. Horde’s MCP tools never receive card numbers or security codes. You can reuse a Link account connected to Grok Bot, but Horde does not register or configure Link MCP support in Grok Bot.

Signup is available to an unbound default-project administrative connection; worker tokens and project-scoped connections cannot use it.

Run the guided command to authorize the initial credit, maximum total charge including fees, and a specific Tuara terms version:

horde config provider signup tuara

The walkthrough proposes $20 credit with a $20.48 total-charge ceiling. The minimum credit is $5, and Link limits the total charge to $500 including fees. An existing provider key requires --replace-existing. Horde preserves the provider’s model and role assignments.

When wallet setup or approval needs more time, continue with horde config provider signup tuara --request-id REFERENCE. Link may require approval for the individual payment in its app. Only successful completion means the verified key is ready for the next invocation; model capacity remains unknown.

Reuse the same request ID after a lost reply or daemon restart. Private receipts in provider-signups/ beside your configuration preserve progress and the signup response. If payment’s outcome is uncertain, Horde puts later payment work on hold until you reconcile it with Tuara and your wallet; it will not charge again or create another account. Before paid submission, use cancel with the same request ID to stop signup. Cancellation cannot reverse a submitted payment.

Automatic Tuara top-ups

Signup does not enable recurring charges. Configure a separate policy with an explicit threshold, credit amount, maximum total per charge including fees, UTC calendar-month limit including fees, terms version, and recurring authorization:

horde config provider topup tuara

Horde checks the balance every 60 seconds and waits five minutes after a successful charge. Link may require approval for each payment. Inspect, advance, or disable the policy with:

horde config provider topup tuara --status
horde config provider topup tuara --check
horde config provider topup tuara --disable

The monthly budget includes fees and is shared by provider aliases for the same Tuara origin and organization within one Horde configuration directory. It does not include spending on other machines or outside this policy. An uncertain payment holds future charges until you reconcile it with Tuara and Link. Disabling stops unpaid work but cannot reverse a submitted payment.

For a test-mode account, set --test-mode on the top-up policy too. Signup and top-ups have passed mock integration tests, and a live Tuara signup quote has been validated. A complete live funding flow has not yet been validated.

Run at startup

horde service install
horde service status
horde service uninstall

Linux uses a systemd service; macOS uses a LaunchDaemon. Installation requests sudo and runs Horde as your user, preserving your selected configuration directory. Uninstalling the service retains data and credentials.