Agent Lifecycle
How to deploy, restart, redeploy, stop, and destroy agents on agentstead.dev.
Every agent moves through a defined set of states. Understanding them helps you know which action to take — and what it costs.
States
| State | Meaning |
|---|---|
DEPLOYING | First-time provisioning — image pulled, container starting |
ONLINE | Running and ready |
RESTARTING | Processes restarting within the same container |
STOPPED | Container stopped — workspace preserved, no compute consumed |
STARTING | Coming back up from stopped |
REDEPLOYING | Container recreated from latest image |
DEGRADED | Online but something is wrong — check Logs |
Actions
Deploy
Creates a new agent from scratch. Choose runtime and region, then AgentStead provisions the container, sets up routing, and returns credentials.
Deployment takes around 90 seconds. Watch the status stream in the dashboard for real-time progress.
See Getting Started for the full deploy flow.
Restart
A soft restart — the same container stays in place but its processes are restarted. Use this when:
- You added or updated a Secret and need it injected
- A process inside the agent has crashed or is behaving unexpectedly
- You want to apply a Settings change that requires a restart
Restart is fast (~10–20 seconds). Workspace is always preserved.
Redeploy
Tears down and recreates the container from the latest image. Use this when:
- AgentStead has pushed an image update you want to pull in
- The container is in a broken state that a restart doesn't fix
- You want a clean environment without destroying workspace data
Redeploy preserves your workspace — files, repos, and installed packages all survive. Secrets and settings are re-injected on startup.
Redeploy takes around 90 seconds, same as initial deploy.
Stop
Stops the container cleanly. The agent shows STOPPED. Your workspace is intact — it's just not running.
Use stop when:
- You want to pause an agent without destroying it
- You're not using it and want to keep the slot available for something else
Stopping an agent does not free the slot. The slot is freed only when you destroy the agent.
Start (from stopped)
Restarts a previously stopped agent. The container comes back up, secrets are re-injected, and the agent returns to ONLINE in roughly 30–60 seconds.
Destroy
Permanently removes the agent and its entire runtime environment. The slot is freed and the agent record is deleted.
Destroying an agent cannot be undone. The workspace, any installed packages, and all runtime state are gone. If you want to keep your workspace, create a backup first.
What destroy removes:
- The container and workspace volume
- Credentials (username, password, runtime token)
- Public URL (immediately released)
- Tailscale connection (if active)
What destroy keeps:
- Your account and subscription
- Secrets (stored at account level, not agent level)
- Backups you already created (these stay in your backup catalog)