# Agent Lifecycle A Daevix agent goes through a well-defined lifecycle: creation, provisioning, bootstrap, steady state, and eventual decommission. This page walks through each phase so you understand what happens behind a command like `dvx agent create`. For the exact commands, see the [CLI guides](/overview/). ## Lifecycle states ``` ┌──────────┐ │ Created │ You request an agent (dvx agent create) └────┬─────┘ Control plane mints an agent ID + bootstrap token │ ▼ ┌────────────┐ Enclave runs provisioning hooks │Provisioning│ External identities created (Okta, AWS, GitHub, …) └────┬───────┘ Hook-generated credentials held in escrow │ ▼ ┌──────────┐ Enclave provisions compute and injects the │ Pending │ bootstrap token; the host boots and the agent │ Bootstrap│ process starts └────┬─────┘ │ ▼ ┌──────────┐ Agent exchanges its bootstrap token for an │ Active │ identity bundle; it is now fully operational └────┬─────┘ │ ├──────────────────────────┐ ▼ ▼ ┌──────────┐ ┌──────────┐ │ Suspended│ You pause │ Revoked │ Credentials │ │ the agent │ │ invalidated └────┬─────┘ └────┬─────┘ │ │ ▼ ▼ ┌──────────┐ ┌────────────┐ │ Resumed │ │Decommission│ Deprovision hooks run, │ (Active) │ │ │ compute destroyed, └──────────┘ └────────────┘ external IDs deleted ``` ## Phase 1: Creation You create an agent with the `dvx` CLI (`dvx agent create`), which calls the control plane. ``` You (dvx) Control Plane Enclave │ │ │ │ Create agent "k8s-deployer" │ │ │─────────────────────────────►│ │ │ │ Create identity record│ │ │ Mint bootstrap token │ │ │ Resolve hooks │ │ │──────────────────────►│ │ │ Run provisioning hooks: │ │ 1. Create Okta service acct │ │ 2. Create AWS IAM role │ │ 3. Create GitHub machine user │ │ 4. Store creds in escrow │ │ │ │ │ Provision compute: │ │ - Select compute target │ │ - Inject bootstrap token │ │ - Start the host │ "Agent provisioning…" │◄──────────────────────│ │◄─────────────────────────────│ │ ``` The control plane writes an `agent.created` event; the enclave receives it over its event stream, generates a bootstrap token, and provisions the agent host. ## Phase 2: Bootstrap The agent boots with only two things: an enclave URL and a bootstrap token. It exchanges the token for a full identity bundle. ``` Agent Host Enclave │ │ │ Host boots │ │ Agent process starts │ │ Reads bootstrap token │ │ │ │ POST /v1/agent/bootstrap │ │ { "token": "abc123…" } │ │──────────────────────────►│ │ │ Validate token (hash + lookup) │ │ Burn token (single-use) │ │ Sign platform JWT (ES256) │ │ Generate refresh token │ │ Decrypt agent secrets │ Identity bundle: │ │ - Platform JWT │ │ - Refresh token │ │ - Agent secrets │ │◄──────────────────────────│ │ │ │ Agent is now active │ ``` The bootstrap token is random 32 bytes with a 1-hour expiry, single-use (burned on first exchange; a replay returns `409`), and stored only as a SHA-256 hash - never in plaintext. ## Phase 3: Steady state While running, the agent operates autonomously and keeps its identity current through periodic JWT renewal. ### JWT renewal loop Platform JWTs have a 5-minute lifetime. The agent renews before expiry: ``` Agent Enclave │ │ │ POST /v1/agent/renew │ │ { "refresh_token": "…" } │ │──────────────────────────►│ │ │ Validate refresh token │ │ Revoke the old refresh token │ │ Sign a new platform JWT │ │ Generate a new refresh token │ │ Decrypt current secrets │ New JWT + refresh token │ │ + current secrets │ │◄──────────────────────────│ ``` Key properties: - Refresh tokens are **single-use** with a 24-hour lifetime. - Each renewal returns both a new JWT and a new refresh token. - **Family-based rotation:** reusing an old refresh token revokes the entire token family (replay detection). - Secrets are re-delivered on each renewal, so credential rotations are picked up automatically. ### LLM usage During steady state the agent makes LLM calls through the proxy, which injects the provider credential the agent never sees and logs every request and response: ``` Agent ──JWT──► LLM proxy ──API key──► Anthropic API ``` ### Credential rotation - **Platform JWT** - short-lived (5 minutes), renewed via the refresh loop. - **External credentials** - managed as agent secrets; rotate by updating the secret value (`dvx secret …`), and the agent receives the new value on its next renewal. - **Bootstrap token** - single-use, burned on first exchange. ## Phase 4: Suspension You can pause an agent. When suspended, its current JWT keeps working until it expires (at most 5 minutes), and renewal attempts return **403 Forbidden** - so the agent stops functioning within one renewal cycle. (With optional Redis-based token-ID blacklisting, revocation is instant.) Resuming returns the agent to active. For an **immediate** cut-off - a kill switch - use `dvx agent isolate `, and `dvx agent restore ` to bring it back. ## Phase 5: Revocation For immediate credential invalidation, `dvx agent revoke ` revokes all of an agent's bootstrap and refresh tokens. The agent cannot renew once its current JWT expires; with token-ID blacklisting the current JWT is invalidated immediately too. ## Phase 6: Decommission Full teardown - `dvx agent delete `: ``` You (dvx) Control Plane Enclave │ │ │ │ Decommission "k8s-deployer" │ │ │─────────────────────────────►│ │ │ │ Mark identity revoked │ │ │──────────────────────►│ │ │ Run deprovisioning hooks: │ │ 1. Disable Okta account │ │ 2. Delete AWS IAM role │ │ 3. Disable GitHub user │ │ 4. Revoke all creds │ │ Destroy compute: │ │ - Terminate container/VM │ │ - Delete storage │ "Agent decommissioned" │◄──────────────────────│ │◄─────────────────────────────│ │ ``` Decommission performs a soft-delete of the agent record, revokes all tokens, runs deprovisioning hooks to clean up external identities, destroys the compute, and preserves the audit trail. ## How agents are isolated When the enclave provisions an agent host, it isolates it from everything it doesn't need: - **One identity per host** - each agent host gets its own OS-level identity and its own short-lived platform credentials. - **Locked-down networking** - agent hosts can reach the enclave, DNS, and the open internet, but not each other or private infrastructure. - **Least-privilege runtime** - agents run as a non-root user with no ambient access to the host's platform credentials. The specifics depend on where the enclave provisions compute (for example, per-agent namespaces on Kubernetes), but the goal is constant: a compromised agent stays contained to its own host. See the [Security Model](/security-model/) for how this fits the broader trust boundaries.