# Secrets
Agent sessions often need credentials to do useful work: a GitHub token for
`gh`, an API key for a deploy tool, or a database URL for a local smoke test.
The unsafe version is to paste those values into the prompt or check them into
an `.env` file the agent can read. Condukt's secrets API keeps the declaration
in trusted code and exposes the resolved values only to tool execution
environments.
## How other agents handle this
Most agent runtimes have converged on one of a few patterns:
* CLI agents such as Claude Code and Aider read credentials from environment
variables, `.env` files, or configuration files.
* Cloud agents such as GitHub Copilot coding agent prepare an ephemeral
development environment and let users attach GitHub Actions variables or
secrets to that environment.
* Secret managers such as 1Password avoid plaintext files by resolving secret
references at runtime. `op run` is the canonical example: it makes secrets
available as environment variables only for the subprocess it starts.
* MCP authorization is moving toward OAuth-based delegated access for remote
tools. That is the right shape for tools that represent SaaS APIs, but it
does not replace local tool credentials like `GH_TOKEN`.
Condukt follows the same separation of concerns: secrets are resolved by
trusted host code, scoped to a session, injected into tool subprocess
environments, and kept out of model context.
## Configuring secrets
Pass `:secrets` at `start_link/1`, return it from an agent module's
`secrets/0` callback, or configure it through `config :condukt, :secrets`.
Keys are the environment variable names exposed to command tools.
```elixir
defmodule MyApp.ReviewAgent do
use Condukt
@impl true
def tools do
[
Condukt.Tools.Read,
{Condukt.Tools.Command, command: "gh"}
]
end
@impl true
def secrets do
[
GH_TOKEN: {:one_password, "op://Engineering/GitHub/token"}
]
end
end
```
The same declaration can be provided per session:
```elixir
{:ok, agent} =
MyApp.ReviewAgent.start_link(
secrets: [
GH_TOKEN: {:one_password, "op://Engineering/GitHub/token"},
DATABASE_URL: {:env, "DATABASE_URL"}
]
)
```
Built-in provider aliases are:
| Alias | Provider | Purpose |
| ----- | -------- | ------- |
| `:one_password` or `:op` | `Condukt.Secrets.Providers.OnePassword` | Resolves a 1Password secret reference with `op read`. |
| `:env` | `Condukt.Secrets.Providers.Env` | Copies a value from the host process environment. |
| `:static` | `Condukt.Secrets.Providers.Static` | Uses a trusted plaintext value. Prefer this for tests. |
Later declarations for the same environment variable replace earlier ones.
## 1Password
The 1Password provider shells out to `op read <ref>` while the session starts.
Authenticate `op` first, or start Condukt with an `OP_SERVICE_ACCOUNT_TOKEN`
that is scoped to the vaults the agent needs.
```elixir
{:ok, agent} =
MyApp.CodingAgent.start_link(
secrets: [
GH_TOKEN: {:one_password, "op://Engineering/GitHub/token"},
STRIPE_API_KEY:
{Condukt.Secrets.Providers.OnePassword,
ref: "op://Engineering/Stripe/api-key",
account: "acme"}
]
)
```
Secret references stay in code. The plaintext value is loaded into the BEAM
process at session initialization and then passed to tool subprocesses as an
environment variable.
## Tool execution
`Condukt.Tools.Bash` passes session secrets through
`Condukt.Sandbox.exec/3` as environment variables:
```elixir
Condukt.run(agent, "Run the local smoke test that needs DATABASE_URL")
```
`Condukt.Tools.Command` merges session secrets with the trusted `:env` values
configured on the tool. Session secrets win if both define the same variable.
```elixir
def tools do
[
{Condukt.Tools.Command, command: "gh", env: [GH_HOST: "github.com"]}
]
end
```
The model cannot add or change environment variables through tool arguments.
It can only invoke the tools you configured.
## Auditing access
Condukt emits value-free telemetry for secret resolution and access:
* `[:condukt, :secrets, :resolve]` when a session resolves secrets.
* `[:condukt, :secrets, :access]` when a tool receives resolved secrets.
Both events include `count` as a measurement and `:names` metadata with
environment variable names such as `["GH_TOKEN"]`. Access events also include
`:tool`, and include `:tool_call_id` when the access comes from a concrete
provider-returned tool call. Secret values are never included in measurements
or metadata.
Attach a handler if you want an audit trail:
```elixir
:telemetry.attach(
"secret-access-audit",
[:condukt, :secrets, :access],
fn _event, measurements, metadata, _config ->
Logger.info("agent secret access",
count: measurements.count,
agent: inspect(metadata.agent),
tool: metadata.tool,
names: metadata.names
)
end,
nil
)
```
## Custom providers
Implement `Condukt.SecretProvider` when your secrets live somewhere else:
```elixir
defmodule MyApp.Secrets.Vault do
@behaviour Condukt.SecretProvider
@impl true
def load(opts) do
MyApp.Vault.read(Keyword.fetch!(opts, :path))
end
end
{:ok, agent} =
MyApp.Agent.start_link(
secrets: [
INTERNAL_TOKEN: {MyApp.Secrets.Vault, path: "agents/internal-token"}
]
)
```
`load/1` returns `{:ok, value}` or `{:error, reason}`. If any secret fails to
load, the session fails to start.
## Redaction and persistence
Resolved secrets are not added to:
* The system prompt
* User messages
* LLM request options
* Session store snapshots
If a tool prints a resolved secret, Condukt exact-match redacts the value from
the tool result before it is stored in history, streamed to subscribers, or
sent back to the model:
```text
[REDACTED:GH_TOKEN]
```
Values shorter than four bytes are not redacted because replacing tiny strings
causes too many false positives.
Under the hood, resolved session secrets become a
`Condukt.Redactors.Secrets` spec and are composed with the session's configured
`:redactor`. Secret redaction runs first so custom redactors cannot transform a
secret before the exact-match replacement has a chance to run.
Redaction is a safety layer, not a permission model. A tool subprocess that
receives `GH_TOKEN` can use it. Scope tokens and 1Password service accounts to
the smallest set of resources that the session needs.
