@agentvalet/dsh
Governed platform access for DeepSeek Harness agents: an agent calls Slack,
GitHub, Gmail, Stripe, or any other AgentValet-connected SaaS platform through
a broker that enforces the owner's grants and approval flow, with no API key
stored on the machine the agent runs on.
Install
dsh plugin --profile web add @agentvalet/dsh
This installs both plugins the bundle ships: av-identity (the agentvalet
service) and av-tools (the four tools below). Restart or reload the profile
after installing.
Connect
An installed but unconnected profile has no identity yet — calls report "not
connected" rather than failing obscurely. To connect it:
- In the AgentValet dashboard, generate a single-use bootstrap token for a
new agent.
- Run the bundle's connect command:
AGENTVALET_BOOTSTRAP_TOKEN=<token> npx agentvalet-dsh-connect --profile web
--token <token> works too; the environment variable just keeps the token out
of your shell history. The command prints the new agent id and nothing else —
never the token, never the key. --help lists the rest of the flags.
Connecting is a command you run, not a tool the agent can call. An
enrolment tool would let an agent bootstrap its own identity with no human in
the loop, and the identity would stop attesting to a person's decision to
create it.
The command generates an RS256 keypair locally and sends only the public
key to AgentValet's /v1/agents/bind endpoint. The private key never leaves
the machine. It is written to $DSH_HOME/agentvalet/<profile>.json
(~/.dsh/agentvalet/... when DSH_HOME is unset) at mode 0600, and the
store refuses outright to write anywhere inside a git working tree.
Once bound, the agent shows up in the dashboard deny-by-default — it can
call nothing until the owner grants it specific platforms and scopes.
A bootstrap token is single-use. Re-running connect on an already-connected
profile is refused rather than silently replacing the identity, so one
agent's audit history can never be laundered into another's.
The routing instructions it writes
Connecting also writes a short routing block into $DSH_HOME/AGENTS.md — the
rule that platform calls go through AgentValet rather than around it. The block
sits between <!-- agentvalet:start --> and <!-- agentvalet:end --> fences:
anything else in that file is yours and is left untouched, and re-running
connect refreshes the region in place instead of appending a second copy.
It is written there because that is where dsh reads. The instruction loader
(@deepseek-ai/dsh-agent-instructions) reads $DSH_HOME/AGENTS.md and then
each directory from the project root down to the session cwd — it never scans
node_modules, so the AGENTS.md shipped inside this package reaches no
model. That copy is documentation for you to read or paste into a project root.
Note it follows $DSH_HOME, not --home: --home only relocates where the
identity is stored, and following it would put the file somewhere nothing reads.
If the write fails, connect says so and still reports the enrolment — by then
the single-use token is spent and the agent exists, so failing the whole command
over a markdown file would strand a real identity.
The block deliberately contains no agent id, owner id, or scope list. This file
lands in a home directory and gets copied into project roots and pasted into
issues; identity in it would leak through ordinary use.
Tools
| Tool | Method | Notes |
|---|
agentvalet_list_platforms | — | Lists platforms and scopes the owner has approved for this agent. Call this before any platform call — grants can change at any time. |
agentvalet_read_platform | Always GET | Read from an approved platform. |
agentvalet_write_platform | POST (default), PUT or PATCH | Create or update. May require owner approval. |
agentvalet_delete_platform | Always DELETE | Usually requires owner approval. |
Every tool takes the platform id and scope string exactly as returned by
agentvalet_list_platforms, plus an endpoint. All four resolve to
{ ok: true, data } on success or { ok: false, error } on failure — a
denial, a pending approval, or a suspended agent all come back as a plain
result the model can read and explain rather than as a thrown error. (That is
a guarantee about our own tool bodies. Argument validation happens in the
harness before our code runs, so a malformed call comes back in dsh's own
isError result shape instead.)
What this does NOT do
- No local policy engine. Every grant, scope, and approval decision is
evaluated by AgentValet's proxy, not by anything running on this machine.
- No vault on disk beyond the agent's own signing key. There is no
platform credential to steal locally — API keys for Slack, GitHub, and the
rest live only at the broker, never on the agent's host.
- No sandboxing. This plugin governs which platform calls succeed; it
is not a substitute for running the harness in a sandbox and pairs with
one rather than replacing it.
- No sub-agent delegation and no attenuated scope re-issue. This bundle
implements neither. It enforces the owner's grants for this one agent, and
that is all it does.
Compatibility
Declared harness range: >=0.1.0-rc.5 <0.2.0. Verified against
@deepseek-ai/dsh@0.1.0-rc.7, @deepseek-ai/cordis@4.0.1, and
@deepseek-ai/dsh-tools@0.1.0-rc.7 — see VERIFICATION.md for what was and
was not confirmed against a real harness run.
