---
title: "Strict agent backends and explicit credentials"
date: "2026-05-18"
---

<Warning>
**Agent backends are now strictly `api` or `acp`.** The legacy `cli` backend and `acp_command` attribute are rejected, and ACP nodes can no longer use API-only model/provider controls.

To migrate:
1. Replace `backend="cli"` with API-backed execution or an explicit ACP process.
2. Replace `acp_command="..."` with `acp.command="..."` for shell command strings.
3. Use `acp.config="..."` for JSON stdio ACP configs.
4. Move `model`, `provider`, `reasoning_effort`, `max_tokens`, and `speed` onto API-backed nodes only.
</Warning>

<Warning>
**Vault credential refs and secret schemas are explicit.** Provider auth refs now use `env:<NAME>` for process environment lookup and `vault:<NAME>` for server-owned vault lookup. API-key secrets are stored as `token`, OAuth records as `oauth`, and file material as `file`.

To migrate:
1. Replace `credential:<NAME>` refs with `vault:<NAME>`.
2. Re-create old `environment` or `credential` secrets with `token`, `oauth`, or `file` schemas.
3. Use `fabro secret set NAME value` for API keys and PAT-style secrets.
</Warning>

## Strict API and ACP backends

Agent execution now has a clear two-backend contract. API-backed stages use Fabro-owned model/provider auth and request controls, while ACP-backed stages launch a user-supplied stdio process that owns its own auth, tools, and protocol behavior.

```dot
implement [label="Implement", backend="acp", acp.command="python3 tools/fake_acp_agent.py"]
```

This removes the old CLI runtime path and prevents ACP execution from accidentally resolving or forwarding provider credentials. ACP events and projections now report process identity such as `command` and optional `config_name` rather than provider/model metadata.

## Explicit vault-backed provider credentials

Fabro now separates process environment credentials from server-owned vault credentials. Provider auth configuration can declare env and vault refs explicitly; current server runtimes use vault-backed provider credentials, while standalone library/CLI flows can opt into env-backed sources.

```toml
[llm.providers.proxy.auth]
credentials = ["env:ACME_GATEWAY_API_KEY", "vault:ACME_GATEWAY_API_KEY"]
```

OpenAI Codex OAuth credentials now live under `vault:OPENAI_CODEX`, and provider catalogs use the same explicit credential-source vocabulary as custom provider settings.

## More

<Accordion title="API">
- Removed old `environment` and `credential` secret schemas in favor of `token`, `oauth`, and `file`
- Session, run, and provider auth paths now consume typed credential sources and typed vault entries
</Accordion>

<Accordion title="Workflows">
- ACP configuration is now split into `acp.command` and `acp.config`
- ACP is restricted to `agent` nodes and rejects API-only model/provider attributes
- Import and stylesheet propagation now preserve the strict backend contract
</Accordion>

<Accordion title="Fixes">
- Server-created detached runs now persist inferred project and workflow names in run metadata
- Manifest preparation now prefers explicit `[workflow].name`, then graph name, then workflow slug when backfilling names
- Legacy vault records created before the explicit credential schema split now migrate correctly at server startup
</Accordion>

<Accordion title="Improvements">
- Provider catalogs now declare process-env and vault credential refs explicitly
- Web stage model extraction now follows the new API/ACP event contract
- Settings are now split into General, Integrations, Security, and Storage pages instead of one oversized overview
</Accordion>
