# Agents Vault — complete documentation

> Agents Vault runs locally. Direct delivery gives trusted code real values. Broker proxy actions use synthetic credentials; protected production custody and installed macOS acceptance remain open.

# Actions and approvals

An action is an operator-saved recipe for one command, credential version, destination, and set of limits. Saving a recipe, granting access, and enabling actions do not approve a run. A live `av run` request waits for a decision, then executes the reviewed command automatically after approval.

The current console supports one active host-proxy recipe per broker. Use synthetic credentials. Start with [configuration and delivery](https://av.syntropika.ai/docs/configuration-and-delivery.md) if you need direct environment delivery instead.

## Configure an action

The local operator console is available at `http://127.0.0.1:14323/` when the daemon is configured with `AVD_APPROVAL_UI=1` and built with its web assets. This setting enables the console; it does not install or initialize a service.

1. Sign in from an operator-controlled browser.
2. Pause action execution before editing credentials, recipes, or permissions.
3. Add or select an active credential in the service vault.
4. In **Actions**, select the credential, set an absolute executable, enter each argument separately, and review runtime and request limits. The broker derives the exact host and credential version.
5. Save the recipe. Saving revokes the affected grants.
6. Grant permission for the new exact recipe, then enable actions.

Review a pending request's executable and argument vector, destination, credential version, runtime, connection quota, and request quota before approving it. Approval permits one attempt by the original waiting CLI connection. A denial prevents that attempt; changing a recipe requires a new matching request.

## Run a synthetic broker action

The service must already have a matching synthetic recipe, its credential permission granted, and actions enabled. Set the non-secret `AVD_AGENT_SOCKET` to the installed socket listed below. With the [project's proxy connection declaration](https://av.syntropika.ai/docs/configuration-and-delivery.md#reference-a-broker-connection), request the exact configured executable and arguments:

```text
av run -- /absolute/path/to/configured-command argument
```

Replace the executable and argument with the operator's recipe. `av run --broker -- COMMAND` also selects the project's connection. The CLI prints `Pending broker request: REQUEST_ID` and stays running for up to 300 seconds while awaiting approval. Review that ID in the authenticated console or through the enrolled MCP Apps flow below. When approved, the same CLI connection executes the frozen command, supplies temporary proxy settings, and reports the result. There is no separate resume command.

Keep the requesting CLI running. Closing its IPC connection revokes its pending approvals and active host-proxy grants. A second process cannot execute or finish the action just by knowing its public request or task ID; reconnecting creates different authority. This boundary does not provide exclusive process identity when a socket or proxy capability is shared. See [limits and trust](https://av.syntropika.ai/docs/limits-and-trust.md).

## Use MCP Apps

`av-mcp` is a stdio adapter for a trusted harness that advertises MCP Apps support. It adopts and reviews an existing live request, with App-only decision tools. It has no execution or credential-reading tool and cannot create a request without a live execution owner. Unsupported clients are refused.

1. Configure the absolute `av-mcp` executable in a compatible harness and set its non-secret `AVD_AGENT_SOCKET` to the installed agent socket.
2. Call `connect_approval`. Its App displays a broker-issued session ID.
3. In the authenticated operator console, refresh Settings and enroll only the exact ID shown in that App. Pending enrollment expires after two minutes.
4. Refresh the App connection. The enrolled harness can submit decisions for 15 minutes and at most 32 requests adopted by that adapter session.
5. Start the versioned project action with `av run` and keep it running. Read its printed request ID.
6. Call `request_proxy_task` with that existing `request_id` and the exact connection, version, host, and command vector. The broker checks the pending frozen intent and retains the original CLI's execution ownership.
7. Review the App's frozen intent and approve or deny it. Approval lets the original waiting CLI execute automatically.

| Tool argument | Required value |
| --- | --- |
| `request_id` | The ID printed by the still-running CLI |
| `connection` | The exact connection ID, such as `service/work` |
| `connection_version` | The version pinned in the project and installed recipe |
| `host` | The exact host in that recipe |
| `command` | The executable and arguments as the exact array of strings |

An altered command, version, or destination is refused. A closed, decided, or already-adopted-by-another-session request cannot be adopted. This MCP workflow uses a versioned connection recipe.

| Platform | Installed agent socket |
| --- | --- |
| Linux | `/run/agents-vault/agent.sock` |
| macOS | `/private/var/db/agents-vault/agent/agent.sock` |

Enrollment delegates bounded decision authority to the trusted harness. App-only visibility is a harness rule, not cryptographic proof of a human click. A malicious enrolled harness can synthesize decisions. A CLI-created request is attached to an MCP session only through explicit adoption; the adapter never takes over its execution connection.

Disconnecting a session prevents further decisions; it does not cancel an already-approved attempt. **Pause and lock** stops actions, discards approvals and loaded credentials, and invalidates console sessions. Signing out ends only that browser session.

The official MCP Apps SDK reference bridge and real Rust adapter have synthetic browser tests. This is not acceptance evidence for a named installed client. Build prerequisites, protocol details, and evidence are in [local approvals and MCP Apps](https://github.com/syntropika/agents-vault/blob/main/docs/approval-flow.md).


---

# Configuration and delivery

`av.toml` describes a project and its requested values. It contains public literals or credential references. A reference describes what a command needs; it does not grant permission to release a credential.

## Choose a delivery path

| Path | What the command receives | Current use |
| --- | --- | --- |
| Public configuration | Selected literal values in its environment | Local project configuration |
| Direct secret delivery | Real selected secret values in its environment | Explicitly trusted commands |
| Same-user proxy preview | A placeholder and proxy settings; the proxy inserts a credential upstream | Synthetic experiments; no protected custody |
| Brokered host proxy | An action capability and temporary proxy settings; the broker holds the synthetic credential | Approved synthetic actions with an installed matching recipe |

Direct delivery cannot hide a value from the recipient. Proxy delivery avoids giving the original credential as the selected environment value, but requires a compatible command and a trustworthy broker boundary. It does not confine the host command. Read [limits and trust](https://av.syntropika.ai/docs/limits-and-trust.md) before choosing it.

## Declare values

The current schema is `2`. Values support scalar `string`, `integer`, and `boolean` types. Each declaration has at most one source:

```toml
schema = 2

[project]
id = "example"

[values.APP_ENV]
type = "string"
value = "development"

[values.SERVICE_TOKEN]
type = "string"
secret = "secret://example/token"
required = true

[environments.production.values.APP_ENV]
type = "string"
value = "production"
```

Select an environment with `av check --env production` or `av run --env production -- COMMAND`. Overrides replace declarations for existing value names. They cannot introduce unknown names. Interpolation and executable resolver expressions are unsupported. Secret references must belong to the declared project.

The default configuration path is `./av.toml`. `av --config PATH` selects another file. Local direct-vault commands also accept `--vault PATH`; installed protected administration rejects these overrides.

## Reference a broker connection

A proxy project uses a versioned connection declaration:

```toml
schema = 2

[project]
id = "example"

[values.SERVICE_TOKEN]
type = "string"
connection = { id = "service/work", version = 1 }
delivery = "proxy"
required = true
```

This is a separate example from the direct configuration above. The current broker path requires exactly one selected connection value and no additional selected values. The broker independently checks the connection version and the installed recipe. A local direct-vault connection is never copied to the service vault automatically.

`av check` checks connection declarations structurally; it does not verify the service's credential version or grant. `av placeholders` emits `<AV_CONNECTION:service/work@1>` for this reference without fetching its credential.

The base CLI is provider-neutral. A label such as `service/work` does not establish API permissions or provider compatibility.

With a matching synthetic recipe, `av run -- COMMAND` or `av run --broker -- COMMAND` keeps its original broker connection open while waiting for a decision. Approval lets that CLI execute automatically. The printed request ID can be used to review or explicitly adopt the live request through MCP; it does not let another connection execute it. See [actions and approvals](https://av.syntropika.ai/docs/actions-and-approvals.md).


---

# Credential lifecycle

Agents Vault has a local direct-user vault and an installed service vault. Choose the vault first: their records, permissions, and unlock state are separate.

## Local connection records

After [initializing the direct vault](https://av.syntropika.ai/docs/quickstart.md), add a record from a trusted operator terminal:

```sh
av connect add service/work --host api.example.test
av connect list
av connect show service/work
```

Use a synthetic value when experimenting with a proxy. `add` uses a hidden prompt and does not contact the provider to validate the credential. `list` and `show` print metadata and policy without the value. New connections deny release. These commands alone do not make a connection usable by `av run`.

Review the current version before changing a connection:

```sh
av connect replace service/work --if-version 1
av connect revoke service/work --if-version 2
av connect disconnect service/work --if-version 2
```

These illustrate a replacement from version 1 to 2. Use the version actually returned by `show`. Replacement increments the version and invalidates existing grants. Revocation removes release grants. Disconnect removes the local credential and its grants; the system retains version history to reject stale changes.

Local changes do not revoke a credential at its issuing service. Revoke or rotate it there separately. A direct recipient may retain a value already delivered to it.

## Generic direct secrets

Generic secrets use project references such as `secret://example/token`:

```sh
av secret add token
av secret policy token
av secret rotate token
av secret revoke token
```

Unlike replacing a connection, rotating a generic secret retains its existing release policy. Review that policy if the replacement should have different access. `av secret list` lists generic secret names without credential values. The current generic secret CLI has no delete subcommand.

## Installed service records

Service installation is a separate prerequisite. `av protected setup` initializes an already installed service's vault. Administration uses a privileged operator helper and a private channel; the agent-facing socket cannot administer the vault.

```text
av protected connect add service/work --host api.example.test
av protected connect show service/work
av protected connect grant service/work 1
```

The grant must match an operator-configured recipe and the observed version. Keep proxy credentials synthetic while custody and installed-platform gates remain open. The [operator connection guide](https://github.com/syntropika/agents-vault/blob/main/docs/local-connections.md) describes setup, replacement, and service locking in detail.

## Recovery and storage

The current storage adapter is SQLCipher. Native keyrings and backend selection are planned. SQLCipher supports encrypted backup, restore, key rotation, and recovery commands; consult `av secret --help` before choosing a recovery operation. Keep recovery material offline and outside agent-accessible paths. Old backups retain their original keys after rotation.

See [storage adapters](https://github.com/syntropika/agents-vault/blob/main/docs/storage-adapters.md) for the persistence boundary and the distinction between future native credential storage and native unlock.


---

# Agents Vault documentation

Agents Vault (`av`) is a local-first tool for project configuration, encrypted credentials, and reviewed CLI actions. Start with local configuration and direct delivery to code you trust. Use synthetic credentials for proxy experiments.

## Find your next step

| You want to… | Read |
| --- | --- |
| Build the CLI and run a small project | [Quickstart](https://av.syntropika.ai/docs/quickstart.md) |
| Choose between environment delivery and proxy delivery | [Configuration and delivery](https://av.syntropika.ai/docs/configuration-and-delivery.md) |
| Add, replace, revoke, or remove a credential | [Credential lifecycle](https://av.syntropika.ai/docs/credential-lifecycle.md) |
| Configure the command an agent may request | [Actions and approvals](https://av.syntropika.ai/docs/actions-and-approvals.md) |
| Understand what the implementation protects | [Limits and trust](https://av.syntropika.ai/docs/limits-and-trust.md) |
| Resolve a failed command or approval | [Troubleshooting](https://av.syntropika.ai/docs/troubleshooting.md) |

These files are also the plain Markdown documentation for agents. Follow their relative links for the full workflow. An agent can inspect public configuration and request an action; credential administration and permission changes belong to the operator. Never place credentials, passphrases, or recovery keys in an agent prompt.

The [implementation status](https://github.com/syntropika/agents-vault/blob/main/docs/implementation-status.md) records test evidence and outstanding release gates. The [storage adapter notes](https://github.com/syntropika/agents-vault/blob/main/docs/storage-adapters.md) describe SQLCipher and planned native integrations. This documentation does not establish production readiness.


---

# Agents Vault

Readable projects. Deliberate access.

Manage project values and encrypted credentials on your machine. Give a trusted command the values it needs, or explore reviewed proxy actions with synthetic credentials.

**Credential boundary:** direct delivery exposes real values to its recipient. Protected proxy custody and installed macOS acceptance remain under development.

[Start with the CLI](https://av.syntropika.ai/docs/quickstart.md) · [Read the docs](https://av.syntropika.ai/docs/index.md) · [Understand the limits](https://av.syntropika.ai/docs/limits-and-trust.md)

## Configuration stays readable. Release stays explicit.

Direct delivery exposes real values. Protected proxy custody remains under development.

## Your command. A deliberate path.

For a reviewed proxy action, the command keeps its HTTPS destination. A temporary capability connects it to the broker, which checks the approved destination and inserts the synthetic credential upstream.

The flow is an illustrative synthetic action: command → Agents Vault → HTTPS provider. It is not a live approval. Host commands are not confined, and a provider may reflect an injected credential.

[Understand proxy delivery](https://av.syntropika.ai/docs/configuration-and-delivery.md)

## Check the shape. Keep the secret.

Declare public values and credential references in `av.toml`. Select environment overrides, validate the configuration, and generate placeholder dotenv files without resolving credentials into them. The local example changes only the public `APP_ENV` value; the credential remains a placeholder.

[Explore project configuration](https://av.syntropika.ai/docs/configuration-and-delivery.md)

## Review the action. Then run.

New credentials have no release grants. For direct secrets, choose the executable and arguments, review the policy, and approve matching runs from an operator terminal. The local console manages credentials, one active action recipe, permissions, and decisions. The waiting CLI can resume after approval. A compatible MCP Apps harness can adopt its live request and present the frozen command, destination, credential version, runtime, and quotas.

[Read about actions and approvals](https://av.syntropika.ai/docs/actions-and-approvals.md)

## Know the current boundary.

SQLCipher is the initial storage adapter. Native keyrings are planned. Proxy actions currently use synthetic credentials; the host command is not confined. Linux and macOS component tests exist, while installed-platform and whole-agent custody gates remain open.

[Build the CLI](https://av.syntropika.ai/docs/quickstart.md) · [See demonstrated behavior](https://github.com/syntropika/agents-vault/blob/main/docs/implementation-status.md)

## Read it your way.

Browse the guides, copy a page, or use the same documentation as plain text. Human guides and agent exports come from the same maintained Markdown.

[Human guides](https://av.syntropika.ai/docs/index.md) · [Agent index](https://av.syntropika.ai/llms.txt) · [Complete Markdown](https://av.syntropika.ai/llms-full.txt)


---

# Limits and trust

Use direct delivery only with code you trust to receive the secret. Use synthetic credentials for proxy and approval tests. Protected production credential custody remains a release gate.

## Direct delivery

A granted child receives real selected values in its environment and can reveal them. The executable image and arguments are pinned by the grant; scripts, imported modules, libraries, and subprocesses remain outside that pinning. An operator must trust that code as well.

The local vault runs under the user's identity. Encrypted storage is not a boundary against every process sharing that identity. A passphrase check or a disclosure message does not authenticate a human approval by itself.

## Proxy delivery

The implementation checks an exact host and applies action lifetime and quotas. An exact host does not restrict API paths or provider-side operations. A provider may reflect an injected credential. A command may ignore proxy settings; the host-client mode does not confine host resources or direct network egress.

The child receives a temporary proxy capability. A copied capability can use the approved destination and remaining quota; it is not an exclusive process identity. A compromised approved host process can also act within that destination and quota. Approval and capability lifecycle must be evaluated together with the operator, harness, broker, and every agent-controlled route.

## Execution connection

The broker assigns execution authority to the original live IPC connection when a request is created. A public request ID, task ID, or displayed owner ID is review context, not authority to execute or finish an action. Another connection cannot claim that authority by knowing those IDs. Closing the original connection revokes its pending approvals and active host-proxy grants; reconnecting does not restore it. MCP adoption permits scoped review and decisions while preserving the CLI connection's execution authority.

This is a connection-lifetime boundary. A deliberately inherited or transferred socket can keep authority alive after the original process exits. The broker does not guarantee original-PID-death detection or protection against a process deliberately sharing its connection. The approved child can also share its proxy capability. These limits remain even though the public-ID execution takeover is rejected.

Real-credential custody remains a release gate. Consult [implementation status](https://github.com/syntropika/agents-vault/blob/main/docs/implementation-status.md) for the original attack reproduction, regression evidence, and remaining platform and whole-agent checks. Keep proxy credentials synthetic.

## Operator and harness authority

The protected broker has a separate service vault and private operator channel. The agent-facing channel cannot administer it. The deployment still needs to prevent an agent sharing the login account from invoking privileged operator helpers.

MCP enrollment explicitly trusts the selected harness to enforce App-only decisions. It grants no credential administration or execution authority. SDK compatibility tests do not prove that every client enforces this rule.

Unlocking storage does not approve a task. Changing storage to a native keyring would not prevent deliberately shared execution connections, malicious harness decisions, or proxy response disclosure.

## Platform and protocol scope

Linux and Apple silicon macOS have component and synthetic CLI evidence. The live public `av run` workflow reached a local synthetic HTTPS provider with `curl` on both platforms; broker and MCP suites also passed on macOS. These tests do not use a genuine provider account. An installed Linux systemd/AppArmor guest has synthetic acceptance evidence. Installed macOS custody, signing, and acceptance remain unverified; native Windows functional execution remains outstanding.

The proxy currently supports HTTP/1.1 CONNECT with HTTP/1.1 inside TLS. HTTP/2, WebSockets, arbitrary CLI compatibility, and broad provider support are not implemented. See the [proxy crate notes](https://github.com/syntropika/agents-vault/blob/main/crates/av-proxy/README.md) for transport constraints.

The [implementation status](https://github.com/syntropika/agents-vault/blob/main/docs/implementation-status.md) is the evidence ledger. The [work queue](https://github.com/syntropika/agents-vault/blob/main/docs/work-queue.md) records remaining gates. Neither successful fixture execution nor a passing unit suite establishes installed operating-system isolation.


---

# Quickstart

This guide runs public project configuration without creating a vault. It then shows how direct secret delivery is authorized. Proxy execution has a separate [action workflow](https://av.syntropika.ai/docs/actions-and-approvals.md).

## Build from a checkout

Use Rust 1.88 or newer. From the repository root:

```sh
cargo build --locked -p av --bin av
./target/debug/av --help
```

The executable is `target/debug/av`. The commands below use `av`; use its absolute path or add that directory to your shell's `PATH` before changing directories. There is no package-manager installation claim in this guide. Platform evidence and packaging progress are listed in [implementation status](https://github.com/syntropika/agents-vault/blob/main/docs/implementation-status.md).

## Run public configuration

In a new project directory:

```sh
av init --project example
```

Add this declaration to the generated `av.toml`:

```toml
[values.APP_ENV]
type = "string"
value = "development"
required = true
```

Check the file and run a trusted command. On Linux or macOS this small example prints only the public value:

```sh
av check
av run -- /usr/bin/printenv APP_ENV
```

Expected output includes `development`. `av check` validates the selected configuration; it does not approve future execution.

## Add a direct secret

From a trusted operator terminal, initialize the local vault once:

```sh
av setup --direct --recovery-file /private/path/av.recovery
av status
```

Replace `/private/path/av.recovery` with a private location outside the agent's reach and move the recovery material offline. Setup prompts for a passphrase. `av status` reports local initialization only; it does not check an installed broker. `av unlock --direct` verifies a passphrase for that process and immediately closes the vault.

Add a value without putting it in a shell argument:

```sh
av secret add token
```

Add its reference to `av.toml`:

```toml
[values.SERVICE_TOKEN]
type = "string"
secret = "secret://example/token"
required = true
```

Choose an absolute executable and arguments that you trust with the value. Grant that exact command from the operator terminal, then run it with the same arguments:

```text
av secret grant token -- /absolute/path/to/trusted-command argument
av run -- /absolute/path/to/trusted-command argument
```

Replace the executable and argument before running these commands. The default grant requires approval for each matching run. The prompt asks you to type `approve`. Direct delivery gives the child the real secret; its loaded code and subprocesses may read it. Changes to the executable, arguments, selected environment, configuration, or working directory can invalidate a grant. See [limits and trust](https://av.syntropika.ai/docs/limits-and-trust.md).

## Import an existing dotenv file

Import requires a new configuration path, so use a fresh project directory or an explicit unused `--config` path:

```sh
av import-env .env --project imported --public APP_ENV
av check
av placeholders --output .env.example
```

Every assignment is secret unless explicitly named with `--public`. Repeat the option for additional public values. Imported secrets start without release grants. The source `.env` remains plaintext; review the import and handle that file separately. The placeholder file contains public literals and references, never resolved credentials.


---

# Troubleshooting

Start by identifying the path: public configuration, direct secret delivery, same-user proxy preview, or brokered action. Local direct-vault commands and installed service commands operate on different vaults.

| Symptom | Check and next step |
| --- | --- |
| `av` is not found | Use the absolute path to the built `target/debug/av`, or add its directory to `PATH`. |
| Configuration already exists | `init` and `import-env` create a new file. Choose a fresh project or an unused `--config` path. |
| Unknown environment or override name | Define the environment in `av.toml`; overrides can replace only existing value names. |
| Missing secret or invalid value type | Confirm the project reference and selected environment. `av check` validates required generic secrets after unlocking the local vault. |
| Direct release denied | Inspect `av secret policy NAME` from an operator terminal. Grant the exact executable and arguments with the same configuration, environment, and directory. |
| Connection version changed | Inspect `av connect show ID` or `av protected connect show ID` in the relevant vault. Review the new version before updating a request or grant. |
| Broker rejects a project configuration | The current path requires exactly one selected connection value. Its version and command must match the installed recipe. |
| Credential edits or action saves are unavailable | Pause action execution in Settings before changing the service configuration. |
| Saved action cannot run | Saving revokes affected permissions. Grant the exact recipe again before enabling actions. |
| MCP client cannot initialize | Check MCP Apps capability support and that `av-mcp` was built with the App assets. There is no chat fallback. |
| MCP session cannot decide | Enroll the exact App session ID in the authenticated console. Check expiry, action ownership, and whether the request belongs to that adapter session. |
| MCP request adoption is refused | Keep the original `av run` process running, use its existing request ID, and match the exact connection version, host, and command. The request must still be pending and cannot belong to another MCP session. |
| Broker approval times out | The CLI waits for up to 300 seconds. Start a new matching request and keep it running while the operator reviews it. |
| A reconnecting client cannot execute or finish | Execution authority belongs to the original IPC connection. A public ID cannot restore it; create a new request instead. |
| Console is unavailable | Check the daemon's `AVD_APPROVAL_UI=1` setting and embedded web assets. It uses loopback port 14323. |
| Proxy settings are rejected | The broker endpoint is fixed at `http://127.0.0.1:14322`; saved settings cannot redirect it to another endpoint. |
| An approved action expires or was already consumed | Review its authoritative state and request a new matching attempt. Approval grants one attempt, not an unlimited reusable permission. |

Do not troubleshoot by weakening a destination, granting an unrelated command, or copying a credential into a prompt. Diagnose proxy behavior using synthetic values and a disposable development broker.

When reporting a problem, include the CLI version, operating system, delivery path, command shape with sensitive arguments removed, and the error message after reviewing it for secrets. Do not attach a vault, key envelope, recovery file, passphrase, proxy capability, or raw secret environment.

For broker execution, follow [actions and approvals](https://av.syntropika.ai/docs/actions-and-approvals.md). The requesting CLI waits and executes automatically after approval; the former `--resume` option is removed.


---