Files
Ben Potter 690d107fdb docs: explain how to keep a workspace running without a connection (#32315)
The answer to "how do I keep a workspace up while a long job or coding
agent runs?" only lived in the [reference
page](https://coder.com/docs/reference/#workspace-agents), which is hard
to find. This adds a **Keep a workspace running without a connection**
section to the scheduling page under Activity detection:

- Background processes (Claude Code in `tmux`, Herdr, `nohup` jobs)
don't count as activity.
- `coder schedule extend` from the CLI, and `PUT /extend` from a script
with a user token.
- **Keep coding agents running:** template examples for Claude Code and
Herdr. A `coder_script` uses the owner's build session token once to
mint a token scoped to `workspace:read` + `workspace:update` and
allow-listed to the workspace. It also installs a `coder-keepalive`
helper. Claude Code calls the helper from `managed_settings` hooks, and
Herdr calls it from a `post_start_script` loop. Neither needs a module
change. Matching README examples: coder/registry#1262.

This deliberately avoids app status / AgentAPI reporting.

<details>
<summary>Validation</summary>

On a local v2.38.8 deployment, I used three Docker workspaces with no
IDE, SSH, or terminal connection. Autostop was 2m, and Claude Code went
through dogfood's AI Gateway running about 30 sequential tool calls over
about 11 minutes. The template used the snippets from this page
verbatim, with the unmodified modules from registry `main`.

| Workspace | Result |
| --- | --- |
| Control (no keep-alive) | Stopped about 1 minute after its deadline
while Claude worked |
| Claude Code hooks | Deadline moved to now + 1h at 13:32, and again at
13:43. No changes after Claude finished |
| Herdr loop | Deadline moved to now + 1h at 13:32. No changes after the
agent went idle |

The scoped token from inside the workspace: `PUT /extend` returns 200.
Stopping or deleting the workspace returns 403. Other workspaces,
`/users/me`, and token creation return 404. A full `GET
/workspaces/{id}` is forbidden with the allow list, which is why the
helper uses `?include_related=latest_build`.

</details>

---

🤖 Generated with Coder Agents using Claude.
2026-11-19 07:46:47 -06:00

4.6 KiB

title
title
Reference

Automation

All actions possible through the Coder dashboard can also be automated. There are several ways to extend/automate Coder:

Quickstart

Generate a token on your Coder deployment by visiting:

https://coder.example.com/settings/tokens

List your workspaces

# CLI
coder ls \
  --url https://coder.example.com \
  --token <your-token> \
  --output json

# REST API (with curl)
curl https://coder.example.com/api/v2/workspaces?q=owner:me \
  -H "Coder-Session-Token: <your-token>"

Documentation

We publish an API reference in our documentation. You can also enable a Swagger endpoint on your Coder deployment.

Use cases

We strive to keep the following use cases up to date, but note that changes to API queries and routes can occur. For the most recent queries and payloads, we recommend checking the relevant documentation.

Users & Groups

Templates

Workspace agents

Workspace agents have a special token that can send logs, metrics, and workspace activity.

  • Custom workspace logs: Expose messages prior to the Coder init script running (for example, pulling image, VM starting, restoring snapshot). coder-logstream-kube uses this to show Kubernetes events, such as image pulls or ResourceQuota restrictions.

    curl -X PATCH https://coder.example.com/api/v2/workspaceagents/me/logs \
    -H "Coder-Session-Token: $CODER_AGENT_TOKEN" \
    -d "{
    \"logs\": [
      {
        \"created_at\": \"$(date -u +'%Y-%m-%dT%H:%M:%SZ')\",
        \"level\": \"info\",
        \"output\": \"Restoring workspace from snapshot: 05%...\"
      }
    ]
    }"
    
  • Manually send workspace activity: Keep a workspace "active," even if there is not an open connection (for example, for a long-running machine learning job).

    This script uses a user token, not the agent token. Create one with coder tokens create, and set it as CODER_SESSION_TOKEN. The script needs jq. It leaves the deadline alone when the workspace already has a later one. This check needs the Coder database to use the UTC time zone, so that the API returns the deadline as a UTC timestamp that ends in Z. If the database uses another time zone, the script sets the deadline to one hour from now on every pass, which can shorten a later deadline.

    #!/bin/bash
    # Send workspace activity as long as the job is still running
    
    while true
    do
    if pgrep -f "my_training_script.py" > /dev/null
    then
      # Aim for a deadline one hour from now. The first date form is GNU, the second is BSD.
      deadline=$(date -u -d '+1 hour' +'%Y-%m-%dT%H:%M:%SZ' 2>/dev/null || date -u -v+1H +'%Y-%m-%dT%H:%M:%SZ')
      current=$(curl -fsS "https://coder.example.com/api/v2/workspaces/$CODER_WORKSPACE_ID" \
      -H "Coder-Session-Token: $CODER_SESSION_TOKEN" | jq -r '.latest_build.deadline')
      # Text comparison, so it is correct only for UTC timestamps, which end in Z.
      if [[ "$current" != *Z || "$current" < "$deadline" ]]
      then
        curl -fsS -X PUT "https://coder.example.com/api/v2/workspaces/$CODER_WORKSPACE_ID/extend" \
        -H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
        -d "{
          \"deadline\": \"$deadline\"
        }"
      fi
    
      # Sleep for 30 minutes (1800 seconds) if the job is running
      sleep 1800
    else
      # Sleep for 1 minute (60 seconds) if the job is not running
      sleep 60
    fi
    done
    

    A user token used in a script is long-lived, so store it in a secret store, not in the script itself.

    For other ways to keep a workspace running, refer to Keep a workspace running without a connection.