Manage Agents

Everything about an agent’s existence - creating it, checking on it, reaching into it, tearing it down - runs through dvx agent. This guide covers the day-to-day operations. For the states an agent moves through, see Agent Lifecycle; for emergency containment and revocation, see Agent lifecycle operations.

Create an agent

dvx broker list                                   # find an enclave to run it on
dvx agent create my-agent --broker-id <id>

Useful flags:

--template <name|id> - start from an agent template (preset image and defaults).
--backend-type managed|external - how the agent’s compute is provided.

The agent starts in created and the enclave provisions it from there.

List and inspect

dvx agent list                 # all your agents and their status
dvx agent get my-agent         # full detail for one agent
dvx status                     # fleet + enclave health at a glance

Add --json to any of these for scripting.

Watch what an agent is doing

dvx agent logs my-agent

Update an agent

dvx agent update my-agent ...

Common configuration (model, system prompt, channels) has its own guide - see Configure your agent.

Reach into a running agent

When you need to get onto the agent’s host:

dvx agent ssh my-agent              # SSH shell via a short-lived certificate
dvx agent connect my-agent          # interactive terminal (WebSocket for managed agents, SSH for external)
dvx agent port-forward my-agent ... # forward a single local port

dvx agent ssh mints an ephemeral Ed25519 key pair, has the broker sign it into a short-lived SSH certificate, and invokes the system ssh binary with it. The key and certificate live only in temp files for the duration of that one command - there’s nothing left over to reuse.

scp, sshfs, and other SSH tooling

To copy files, mount the agent’s filesystem, or drive any other SSH-based tool, open a tunnel instead of a one-shot session. dvx agent tunnel starts a background SSH agent (an ssh-agent-compatible socket serving an auto-renewing certificate) alongside the WireGuard tunnel, and forwards a local port to the agent’s SSH port:

dvx agent tunnel my-agent

It prints the socket and port to use:

SSH_AUTH_SOCK=<socket> ssh -p <port> agent@127.0.0.1
SSH_AUTH_SOCK=<socket> scp -P <port> file.txt agent@127.0.0.1:
SSH_AUTH_SOCK=<socket> sshfs -p <port> agent@127.0.0.1:/ /mnt/agent

Leave the dvx agent tunnel command running for as long as you need the socket; Ctrl+C tears down the tunnel (and revokes the socket) when you’re done. Pass --no-ssh-agent to skip starting it if you only need the WireGuard tunnel itself.

Isolate an agent

To cut an agent off immediately without deleting it - for example, while investigating unexpected behavior:

dvx agent isolate my-agent --reason "investigating unexpected network calls"
dvx agent restore my-agent    # bring it back

See Agent lifecycle operations for the full set of containment controls (isolate, revoke, delete) and how to choose between them.

Reprovision

If an agent’s host is unhealthy or you’ve changed something that only takes effect at provision time, re-run provisioning:

dvx agent reprovision my-agent

Decommission

Full teardown - revokes tokens, runs deprovisioning hooks, destroys the compute, and preserves the audit trail:

dvx agent delete my-agent

This is permanent. If you just want to pause or cut off an agent, see Isolate an agent above.