Skip to main content

Agents

This guide explains how to operate the Frontdoor Agents in order to create Shares.

Why this matters​

  • Agents run at the edge or within your infrastructure and connect to the Frontdoor service.
  • Enrollment creates credentials to bootstrap a new agent instance.
  • Use status/version to monitor health and rollout upgrades.

Operations​

Assumptions​

- Authorization: Bearer YOUR_ACCESS_TOKEN
- Accept: application/hal+json or application/json

Enroll a Frontdoor Agent​

Create an agent enrollment​

To run an agent and register an environment.

Request example

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/agents/enrollments

Example response

{
  "frontdoorId": "3d6d2b6e-...",
  "enrollmentCode": "ENR-XYZ-123",
  "expiresAt": "2025-08-31T12:00:00Z"
}

Execute the Frontdoor Agent​

Download and install a Frontdoor Agent appropriate for your operating system. This example will assume linux and that the agent software is available on the path.

frontdoor-agent start --enrollment-token ENR-XYZ-123

Notes

  • After enrollment, the running agent creates an Environment entity under the Frontdoor. See Environments guide.

Get agent status​

Request example

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/agents/agt_abc123/status

Example response

{
  "frontdoorId" : "b05ab927-270e-47d9-a332-efc9e4c613ec",
  "shares" : [ {
    "token" : "share1",
    "shareMode" : "public",
    "backendMode" : "proxy",
    "reserved" : true,
    "frontendEndpoints" : [ "https://share1.shares.netfoundry.io" ],
    "backendEndpoint" : "https://google.com",
    "status" : "online"
  } ]
}

Get agent version​

Request example

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/agents/agt_abc123/version

Example response

{
  "frontdoorId" : "b05ab927-270e-47d9-a332-efc9e4c613ec",
  "version" : "1.0.1"
}

Delete an agent​

Request example

curl -s -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/agents/agt_abc123

The delete request has an empty response.

Technical Notes​

Paths​

- GET /frontdoor/agents/bootstrap-token/{enrollmentCode}
- POST /frontdoor/\{frontdoorId\}/agents/enrollments
- GET /frontdoor/\{frontdoorId\}/agents/{agentId}/status
- GET /frontdoor/\{frontdoorId\}/agents/{agentId}/version
- DELETE /frontdoor/\{frontdoorId\}/agents/{agentId}

Common errors​

Common errors​

400 Bad Request (client error)​

{
  "error": "invalid_request",
  "message": "Value for <property> must be of <type>"
}

Possible reasons include:

  • Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
  • Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.

401 Unauthorized (missing/expired token)​

{
  "error": "unauthorized",
  "message": "Bearer token is missing or invalid"
}

Possible reasons include:

  • Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
  • Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.

403 Forbidden (not_authorized)​

{
  "error": "not_found",
  "message": "Frontdoor 3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c not found"
}

Possible reasons include:

  • Invalid token: The token is not valid.
  • The token does not grant access to the requested resource.
  • Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
  • Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.