Agents | Coder Docs

Agents

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

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

Parameters

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

Example responses

{
  "session_token": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.WorkspaceAgentAuthenticateResponse

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

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

Parameters

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

Example responses

{
  "session_token": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.WorkspaceAgentAuthenticateResponse

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

{
  "json_web_token": "string"
}

Parameters

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

Example responses

{
  "session_token": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.WorkspaceAgentAuthenticateResponse

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

Submit workspace agent application health

Code samples

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

POST /workspaceagents/me/app-health

{
  "healths": {
    "property1": "disabled",
    "property2": "disabled"
  }
}

Parameters

Name	In	Type	Required	Description
`body`	body	codersdk.PostWorkspaceAppHealthsRequest	true	Application health request

Responses

Status	Meaning	Description	Schema
200	OK	OK

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

Coordinate workspace agent via Tailnet

Code samples

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

GET /workspaceagents/me/coordinate

It accepts a WebSocket connection to an agent that listens to incoming connections and publishes node updates.

Responses

Status	Meaning	Description	Schema
101	Switching Protocols	Switching Protocols

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

Get workspace agent Git auth

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/me/gitauth?url=http%3A%2F%2Fexample.com \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/me/gitauth

Parameters

Name	In	Type	Required	Description
`url`	query	string(uri)	true	Git URL
`listen`	query	boolean	false	Wait for a new token to be issued

Example responses

{
  "password": "string",
  "url": "string",
  "username": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.WorkspaceAgentGitAuthResponse

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

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

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.AgentGitSSHKey

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

Get authorized workspace agent metadata

Code samples

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

GET /workspaceagents/me/metadata

Example responses

{
  "apps": [
    {
      "command": "string",
      "display_name": "string",
      "external": true,
      "health": "disabled",
      "healthcheck": {
        "interval": 0,
        "threshold": 0,
        "url": "string"
      },
      "icon": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "sharing_level": "owner",
      "slug": "string",
      "subdomain": true,
      "url": "string"
    }
  ],
  "derpmap": {
    "omitDefaultRegions": true,
    "regions": {
      "property1": {
        "avoid": true,
        "embeddedRelay": true,
        "nodes": [
          {
            "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": [
          {
            "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"
      }
    }
  },
  "directory": "string",
  "environment_variables": {
    "property1": "string",
    "property2": "string"
  },
  "git_auth_configs": 0,
  "motd_file": "string",
  "startup_script": "string",
  "vscode_port_proxy_uri": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.WorkspaceAgentMetadata

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

Submit workspace agent stats

Code samples

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

POST /workspaceagents/me/report-stats

{
  "conns_by_proto": {
    "property1": 0,
    "property2": 0
  },
  "num_comms": 0,
  "rx_bytes": 0,
  "rx_packets": 0,
  "tx_bytes": 0,
  "tx_packets": 0
}

Parameters

Name	In	Type	Required	Description
`body`	body	codersdk.AgentStats	true	Stats request

Example responses

{
  "report_interval": 0
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.AgentStatsResponse

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

{
  "apps": [
    {
      "command": "string",
      "display_name": "string",
      "external": true,
      "health": "disabled",
      "healthcheck": {
        "interval": 0,
        "threshold": 0,
        "url": "string"
      },
      "icon": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "sharing_level": "owner",
      "slug": "string",
      "subdomain": true,
      "url": "string"
    }
  ],
  "architecture": "string",
  "connection_timeout_seconds": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "directory": "string",
  "disconnected_at": "2019-08-24T14:15:22Z",
  "environment_variables": {
    "property1": "string",
    "property2": "string"
  },
  "first_connected_at": "2019-08-24T14:15:22Z",
  "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
    }
  },
  "name": "string",
  "operating_system": "string",
  "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
  "startup_script": "string",
  "status": "connecting",
  "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

{
  "derp_map": {
    "omitDefaultRegions": true,
    "regions": {
      "property1": {
        "avoid": true,
        "embeddedRelay": true,
        "nodes": [
          {
            "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": [
          {
            "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"
      }
    }
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.WorkspaceAgentConnectionInfo

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

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

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.ListeningPortsResponse

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.

See an opportunity to improve our docs? Make an edit.

On this page