shishantbiswas/coder
1
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-06-03 21:18:24 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
f95a5202bf243df309d0cd4f46d6436e82413fbe
coder/docs/reference/api/agents.md
T
Sas Swart 5b6b7719df fix: make prebuild claiming durable and idempotent (#23108) 
## Problem

When a prebuilt workspace is claimed, the agent reinitializes via a
single fire-and-forget pubsub event over SSE. If the agent's SSE
connection is interrupted at claim time, the event is permanently lost —
the workspace is stuck with no self-healing path.

Additionally, regular (non-prebuild) workspaces had no way to opt out of
the `/reinit` polling loop — agents would reconnect indefinitely to an
endpoint that would never send them anything useful.

## Root Cause

`workspaceAgentReinit` fetches the workspace (with its current
`owner_id`) via `GetWorkspaceByAgentID`, but never checked whether a
claim already happened. It only subscribed to pubsub for future events.
The database already has durable claim state (`owner_id` changes from
`PrebuildsSystemUserID` to the real user), but no layer ever consulted
it on reconnection.

## Solution

### Server-side durable check with first-build-initiator gating

**TOCTOU-safe ordering**: Subscribe to pubsub claim events *before* any
durable checks, so a claim that fires during the check is buffered in
the channel rather than lost.

**First-build-initiator gating**: When `!workspace.IsPrebuild()` (owner
is no longer the system user), look up the first build's `InitiatorID`.
The prebuild reconciler always uses `PrebuildsSystemUserID` as the
initiator. This distinguishes claimed prebuilds from regular workspaces
without any SQL schema changes.

- **Regular workspace** (first build initiator ≠ system user) → **409
Conflict**, agent stops reconnecting
- **Claimed prebuild, build completed** → pre-seed channel with reinit
event and close it, transmitter delivers one-shot then exits
- **Claimed prebuild, build in-progress** → fall through to pubsub
subscription, agent waits for completion event
- **Unclaimed prebuild** → pubsub subscription (existing happy path)

### Declarative reinit events (defense-in-depth)

- Added `UserID` field to `ReinitializationEvent` with JSON tags
- Switched pubsub serialization from raw string to JSON (with
backward-compat fallback for rolling upgrades)
- Populated `UserID` at both the publish site and the durable check

### Agent SDK: 409 handling

`WaitForReinitLoop` detects 409 Conflict from the server and closes the
`reinitEvents` channel, cleanly exiting the retry goroutine.

### Agent CLI: fixed two bugs + added reinitCtx

- **Closed channel (`!ok`)**: now blocks on `<-ctx.Done()` instead of
`continue`, keeping the current agent running. Previously this would
leak agents by skipping `agnt.Close()` and re-entering the loop.
- **Duplicate owner reinit**: cancels `reinitCtx` (stops the reinit
goroutine), then blocks on `<-ctx.Done()`. Previously `continue` would
skip cleanup and create a new agent on the next loop iteration.
- **`reinitCtx`**: a cancellable child of `ctx` passed to
`WaitForReinitLoop`, allowing the agent to stop the reinit HTTP polling
after reinit completes.

### Agent-side idempotency

Tracks `lastOwnerID` in the agent reinit loop — duplicate events for the
same owner are skipped.

## Testing

- **"unclaimed prebuild receives reinit via pubsub"**: prebuild owned by
system user, pubsub event triggers reinit
- **"claimed prebuild receives one-shot reinit on reconnect"**: first
build by system user, owner changed, build completed → immediate reinit
(no pubsub needed)
- **"claimed prebuild waits during in-progress claim build"**: claimed
but build still running → no reinit until build completes
- **"regular workspace gets 409"**: first build by real user → 409
Conflict, agent stops polling
- Updated claim publisher/listener tests: verify `UserID` survives JSON
round-trip + backward compat with raw string payloads
- Updated SSE round-trip test: verify `UserID` survives transmit →
receive cycle

Fixes #22359

## Rolling upgrade note

During a rolling deploy where old coderd instances coexist with new
ones, the pubsub `ReinitializationEvent` has a new `workspace_id` field
(JSON key `workspace_id`). Old publishers send a raw reason string
instead of JSON; the new listener gracefully falls back by treating the
entire payload as the reason and filling in `WorkspaceID` from context.
The only visible effect during the upgrade window is that `WorkspaceID`
may be the zero UUID in agent-side logs — this is cosmetic and resolves
once all instances are updated.
2026-04-02 23:51:02 +02:00

41 KiB
Generated
Raw Blame History

Agents

Get DERP map updates

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/derp-map \
  -H 'Coder-Session-Token: API_KEY'

GET /derp-map

Responses

Status Meaning Description Schema
101 Switching Protocols Switching Protocols

To perform this operation, you must be authenticated. Learn more.

User-scoped tailnet RPC connection

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/tailnet \
  -H 'Coder-Session-Token: API_KEY'

GET /tailnet

Responses

Status Meaning Description Schema
101 Switching Protocols Switching Protocols

To perform this operation, you must be authenticated. Learn more.

Authenticate agent on AWS instance

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/workspaceagents/aws-instance-identity \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /workspaceagents/aws-instance-identity

Body parameter

{
  "document": "string",
  "signature": "string"
}

Parameters

Name In Type Required Description
body body agentsdk.AWSInstanceIdentityToken true Instance identity token

Example responses

200 Response

{
  "session_token": "string"
}

Responses

Status Meaning Description Schema
200 OK OK agentsdk.AuthenticateResponse

To perform this operation, you must be authenticated. Learn more.

Authenticate agent on Azure instance

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/workspaceagents/azure-instance-identity \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /workspaceagents/azure-instance-identity

Body parameter

{
  "encoding": "string",
  "signature": "string"
}

Parameters

Name In Type Required Description
body body agentsdk.AzureInstanceIdentityToken true Instance identity token

Example responses

200 Response

{
  "session_token": "string"
}

Responses

Status Meaning Description Schema
200 OK OK agentsdk.AuthenticateResponse

To perform this operation, you must be authenticated. Learn more.

Authenticate agent on Google Cloud instance

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/workspaceagents/google-instance-identity \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /workspaceagents/google-instance-identity

Body parameter

{
  "json_web_token": "string"
}

Parameters

Name In Type Required Description
body body agentsdk.GoogleInstanceIdentityToken true Instance identity token

Example responses

200 Response

{
  "session_token": "string"
}

Responses

Status Meaning Description Schema
200 OK OK agentsdk.AuthenticateResponse

To perform this operation, you must be authenticated. Learn more.

Patch workspace agent app status

Code samples

# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/workspaceagents/me/app-status \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PATCH /workspaceagents/me/app-status

Body parameter

{
  "app_slug": "string",
  "icon": "string",
  "message": "string",
  "needs_user_attention": true,
  "state": "working",
  "uri": "string"
}

Parameters

Name In Type Required Description
body body agentsdk.PatchAppStatus true app status

Example responses

200 Response

{
  "detail": "string",
  "message": "string",
  "validations": [
    {
      "detail": "string",
      "field": "string"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.Response

To perform this operation, you must be authenticated. Learn more.

Get workspace agent external auth

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/me/external-auth?match=string&id=string \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/me/external-auth

Parameters

Name In Type Required Description
match query string true Match
id query string true Provider ID
listen query boolean false Wait for a new token to be issued

Example responses

200 Response

{
  "access_token": "string",
  "password": "string",
  "token_extra": {},
  "type": "string",
  "url": "string",
  "username": "string"
}

Responses

Status Meaning Description Schema
200 OK OK agentsdk.ExternalAuthResponse

To perform this operation, you must be authenticated. Learn more.

Removed: Get workspace agent git auth

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/me/gitauth?match=string&id=string \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/me/gitauth

Parameters

Name In Type Required Description
match query string true Match
id query string true Provider ID
listen query boolean false Wait for a new token to be issued

Example responses

200 Response

{
  "access_token": "string",
  "password": "string",
  "token_extra": {},
  "type": "string",
  "url": "string",
  "username": "string"
}

Responses

Status Meaning Description Schema
200 OK OK agentsdk.ExternalAuthResponse

To perform this operation, you must be authenticated. Learn more.

Get workspace agent Git SSH key

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/me/gitsshkey \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/me/gitsshkey

Example responses

200 Response

{
  "private_key": "string",
  "public_key": "string"
}

Responses

Status Meaning Description Schema
200 OK OK agentsdk.GitSSHKey

To perform this operation, you must be authenticated. Learn more.

Post workspace agent log source

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/workspaceagents/me/log-source \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /workspaceagents/me/log-source

Body parameter

{
  "display_name": "string",
  "icon": "string",
  "id": "string"
}

Parameters

Name In Type Required Description
body body agentsdk.PostLogSourceRequest true Log source request

Example responses

200 Response

{
  "created_at": "2019-08-24T14:15:22Z",
  "display_name": "string",
  "icon": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "workspace_agent_id": "7ad2e618-fea7-4c1a-b70a-f501566a72f1"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.WorkspaceAgentLogSource

To perform this operation, you must be authenticated. Learn more.

Patch workspace agent logs

Code samples

# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/workspaceagents/me/logs \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PATCH /workspaceagents/me/logs

Body parameter

{
  "log_source_id": "string",
  "logs": [
    {
      "created_at": "string",
      "level": "trace",
      "output": "string"
    }
  ]
}

Parameters

Name In Type Required Description
body body agentsdk.PatchLogs true logs

Example responses

200 Response

{
  "detail": "string",
  "message": "string",
  "validations": [
    {
      "detail": "string",
      "field": "string"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.Response

To perform this operation, you must be authenticated. Learn more.

Get workspace agent reinitialization

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/me/reinit \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/me/reinit

Parameters

Name In Type Required Description
wait query boolean false Opt in to durable reinit checks

Example responses

200 Response

{
  "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
  "reason": "prebuild_claimed",
  "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
}

Responses

Status Meaning Description Schema
200 OK OK agentsdk.ReinitializationEvent
409 Conflict Conflict codersdk.Response

To perform this operation, you must be authenticated. Learn more.

Get workspace agent by ID

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/{workspaceagent} \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/{workspaceagent}

Parameters

Name In Type Required Description
workspaceagent path string(uuid) true Workspace agent ID

Example responses

200 Response

{
  "api_version": "string",
  "apps": [
    {
      "command": "string",
      "display_name": "string",
      "external": true,
      "group": "string",
      "health": "disabled",
      "healthcheck": {
        "interval": 0,
        "threshold": 0,
        "url": "string"
      },
      "hidden": true,
      "icon": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "open_in": "slim-window",
      "sharing_level": "owner",
      "slug": "string",
      "statuses": [
        {
          "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
          "app_id": "affd1d10-9538-4fc8-9e0b-4594a28c1335",
          "created_at": "2019-08-24T14:15:22Z",
          "icon": "string",
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "message": "string",
          "needs_user_attention": true,
          "state": "working",
          "uri": "string",
          "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
        }
      ],
      "subdomain": true,
      "subdomain_name": "string",
      "tooltip": "string",
      "url": "string"
    }
  ],
  "architecture": "string",
  "connection_timeout_seconds": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "directory": "string",
  "disconnected_at": "2019-08-24T14:15:22Z",
  "display_apps": [
    "vscode"
  ],
  "environment_variables": {
    "property1": "string",
    "property2": "string"
  },
  "expanded_directory": "string",
  "first_connected_at": "2019-08-24T14:15:22Z",
  "health": {
    "healthy": false,
    "reason": "agent has lost connection"
  },
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "instance_id": "string",
  "last_connected_at": "2019-08-24T14:15:22Z",
  "latency": {
    "property1": {
      "latency_ms": 0,
      "preferred": true
    },
    "property2": {
      "latency_ms": 0,
      "preferred": true
    }
  },
  "lifecycle_state": "created",
  "log_sources": [
    {
      "created_at": "2019-08-24T14:15:22Z",
      "display_name": "string",
      "icon": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "workspace_agent_id": "7ad2e618-fea7-4c1a-b70a-f501566a72f1"
    }
  ],
  "logs_length": 0,
  "logs_overflowed": true,
  "name": "string",
  "operating_system": "string",
  "parent_id": {
    "uuid": "string",
    "valid": true
  },
  "ready_at": "2019-08-24T14:15:22Z",
  "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
  "scripts": [
    {
      "cron": "string",
      "display_name": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "log_path": "string",
      "log_source_id": "4197ab25-95cf-4b91-9c78-f7f2af5d353a",
      "run_on_start": true,
      "run_on_stop": true,
      "script": "string",
      "start_blocks_login": true,
      "timeout": 0
    }
  ],
  "started_at": "2019-08-24T14:15:22Z",
  "startup_script_behavior": "blocking",
  "status": "connecting",
  "subsystems": [
    "envbox"
  ],
  "troubleshooting_url": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "version": "string"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.WorkspaceAgent

To perform this operation, you must be authenticated. Learn more.

Get connection info for workspace agent

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/connection \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/{workspaceagent}/connection

Parameters

Name In Type Required Description
workspaceagent path string(uuid) true Workspace agent ID

Example responses

200 Response

{
  "derp_force_websockets": true,
  "derp_map": {
    "homeParams": {
      "regionScore": {
        "property1": 0,
        "property2": 0
      }
    },
    "omitDefaultRegions": true,
    "regions": {
      "property1": {
        "avoid": true,
        "embeddedRelay": true,
        "nodes": [
          {
            "canPort80": true,
            "certName": "string",
            "derpport": 0,
            "forceHTTP": true,
            "hostName": "string",
            "insecureForTests": true,
            "ipv4": "string",
            "ipv6": "string",
            "name": "string",
            "regionID": 0,
            "stunonly": true,
            "stunport": 0,
            "stuntestIP": "string"
          }
        ],
        "regionCode": "string",
        "regionID": 0,
        "regionName": "string"
      },
      "property2": {
        "avoid": true,
        "embeddedRelay": true,
        "nodes": [
          {
            "canPort80": true,
            "certName": "string",
            "derpport": 0,
            "forceHTTP": true,
            "hostName": "string",
            "insecureForTests": true,
            "ipv4": "string",
            "ipv6": "string",
            "name": "string",
            "regionID": 0,
            "stunonly": true,
            "stunport": 0,
            "stuntestIP": "string"
          }
        ],
        "regionCode": "string",
        "regionID": 0,
        "regionName": "string"
      }
    }
  },
  "disable_direct_connections": true,
  "hostname_suffix": "string"
}

Responses

Status Meaning Description Schema
200 OK OK workspacesdk.AgentConnectionInfo

To perform this operation, you must be authenticated. Learn more.

Get running containers for workspace agent

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/containers?label=string \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/{workspaceagent}/containers

Parameters

Name In Type Required Description
workspaceagent path string(uuid) true Workspace agent ID
label query string(key=value) true Labels

Example responses

200 Response

{
  "containers": [
    {
      "created_at": "2019-08-24T14:15:22Z",
      "id": "string",
      "image": "string",
      "labels": {
        "property1": "string",
        "property2": "string"
      },
      "name": "string",
      "ports": [
        {
          "host_ip": "string",
          "host_port": 0,
          "network": "string",
          "port": 0
        }
      ],
      "running": true,
      "status": "string",
      "volumes": {
        "property1": "string",
        "property2": "string"
      }
    }
  ],
  "devcontainers": [
    {
      "agent": {
        "directory": "string",
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string"
      },
      "config_path": "string",
      "container": {
        "created_at": "2019-08-24T14:15:22Z",
        "id": "string",
        "image": "string",
        "labels": {
          "property1": "string",
          "property2": "string"
        },
        "name": "string",
        "ports": [
          {
            "host_ip": "string",
            "host_port": 0,
            "network": "string",
            "port": 0
          }
        ],
        "running": true,
        "status": "string",
        "volumes": {
          "property1": "string",
          "property2": "string"
        }
      },
      "dirty": true,
      "error": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "status": "running",
      "subagent_id": {
        "uuid": "string",
        "valid": true
      },
      "workspace_folder": "string"
    }
  ],
  "warnings": [
    "string"
  ]
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.WorkspaceAgentListContainersResponse

To perform this operation, you must be authenticated. Learn more.

Delete devcontainer for workspace agent

Code samples

# Example request using curl
curl -X DELETE http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/containers/devcontainers/{devcontainer} \
  -H 'Coder-Session-Token: API_KEY'

DELETE /workspaceagents/{workspaceagent}/containers/devcontainers/{devcontainer}

Parameters

Name In Type Required Description
workspaceagent path string(uuid) true Workspace agent ID
devcontainer path string true Devcontainer ID

Responses

Status Meaning Description Schema
204 No Content No Content

To perform this operation, you must be authenticated. Learn more.

Recreate devcontainer for workspace agent

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/containers/devcontainers/{devcontainer}/recreate \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /workspaceagents/{workspaceagent}/containers/devcontainers/{devcontainer}/recreate

Parameters

Name In Type Required Description
workspaceagent path string(uuid) true Workspace agent ID
devcontainer path string true Devcontainer ID

Example responses

202 Response

{
  "detail": "string",
  "message": "string",
  "validations": [
    {
      "detail": "string",
      "field": "string"
    }
  ]
}

Responses

Status Meaning Description Schema
202 Accepted Accepted codersdk.Response

To perform this operation, you must be authenticated. Learn more.

Watch workspace agent for container updates

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/containers/watch \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/{workspaceagent}/containers/watch

Parameters

Name In Type Required Description
workspaceagent path string(uuid) true Workspace agent ID

Example responses

200 Response

{
  "containers": [
    {
      "created_at": "2019-08-24T14:15:22Z",
      "id": "string",
      "image": "string",
      "labels": {
        "property1": "string",
        "property2": "string"
      },
      "name": "string",
      "ports": [
        {
          "host_ip": "string",
          "host_port": 0,
          "network": "string",
          "port": 0
        }
      ],
      "running": true,
      "status": "string",
      "volumes": {
        "property1": "string",
        "property2": "string"
      }
    }
  ],
  "devcontainers": [
    {
      "agent": {
        "directory": "string",
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string"
      },
      "config_path": "string",
      "container": {
        "created_at": "2019-08-24T14:15:22Z",
        "id": "string",
        "image": "string",
        "labels": {
          "property1": "string",
          "property2": "string"
        },
        "name": "string",
        "ports": [
          {
            "host_ip": "string",
            "host_port": 0,
            "network": "string",
            "port": 0
          }
        ],
        "running": true,
        "status": "string",
        "volumes": {
          "property1": "string",
          "property2": "string"
        }
      },
      "dirty": true,
      "error": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "status": "running",
      "subagent_id": {
        "uuid": "string",
        "valid": true
      },
      "workspace_folder": "string"
    }
  ],
  "warnings": [
    "string"
  ]
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.WorkspaceAgentListContainersResponse

To perform this operation, you must be authenticated. Learn more.

Coordinate workspace agent

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/coordinate \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/{workspaceagent}/coordinate

Parameters

Name In Type Required Description
workspaceagent path string(uuid) true Workspace agent ID

Responses

Status Meaning Description Schema
101 Switching Protocols Switching Protocols

To perform this operation, you must be authenticated. Learn more.

Get listening ports for workspace agent

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/listening-ports \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/{workspaceagent}/listening-ports

Parameters

Name In Type Required Description
workspaceagent path string(uuid) true Workspace agent ID

Example responses

200 Response

{
  "ports": [
    {
      "network": "string",
      "port": 0,
      "process_name": "string"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.WorkspaceAgentListeningPortsResponse

To perform this operation, you must be authenticated. Learn more.

Get logs by workspace agent

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/logs \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/{workspaceagent}/logs

Parameters

Name In Type Required Description
workspaceagent path string(uuid) true Workspace agent ID
before query integer false Before log id
after query integer false After log id
follow query boolean false Follow log stream
no_compression query boolean false Disable compression for WebSocket connection
format query string false Log output format. Accepted: 'json' (default), 'text' (plain text with RFC3339 timestamps and ANSI colors). Not supported with follow=true.

Enumerated Values

Parameter Value(s)
format json, text

Example responses

200 Response

[
  {
    "created_at": "2019-08-24T14:15:22Z",
    "id": 0,
    "level": "trace",
    "output": "string",
    "source_id": "ae50a35c-df42-4eff-ba26-f8bc28d2af81"
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.WorkspaceAgentLog

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» created_at string(date-time) false
» id integer false
» level codersdk.LogLevel false
» output string false
» source_id string(uuid) false

Enumerated Values

Property Value(s)
level debug, error, info, trace, warn

To perform this operation, you must be authenticated. Learn more.

Open PTY to workspace agent

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/pty \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/{workspaceagent}/pty

Parameters

Name In Type Required Description
workspaceagent path string(uuid) true Workspace agent ID

Responses

Status Meaning Description Schema
101 Switching Protocols Switching Protocols

To perform this operation, you must be authenticated. Learn more.

Removed: Get logs by workspace agent

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/startup-logs \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/{workspaceagent}/startup-logs

Parameters

Name In Type Required Description
workspaceagent path string(uuid) true Workspace agent ID
before query integer false Before log id
after query integer false After log id
follow query boolean false Follow log stream
no_compression query boolean false Disable compression for WebSocket connection

Example responses

200 Response

[
  {
    "created_at": "2019-08-24T14:15:22Z",
    "id": 0,
    "level": "trace",
    "output": "string",
    "source_id": "ae50a35c-df42-4eff-ba26-f8bc28d2af81"
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.WorkspaceAgentLog

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» created_at string(date-time) false
» id integer false
» level codersdk.LogLevel false
» output string false
» source_id string(uuid) false

Enumerated Values

Property Value(s)
level debug, error, info, trace, warn

To perform this operation, you must be authenticated. Learn more.

Reference in New Issue View Git Blame Copy Permalink