---
title: Agent Remoting
sidebar_label: Remoting
sidebar_position: 20
---

As of `v1.0.5` the zrok Agent and controller support secure, opt-in remote control for creating shares and accesses through the central zrok API.

## Enabling Agent Remoting in the zrok Controller

Create an identity for your zrok controller to use for interacting with remote agents:

```
$ zrok admin create identity agentremoting
zrok identity 'agentremoting' created with ziti id 'WEfGMIx-e4'
```
:::note
The indentity can be named anything; I chose `agentremoting` just for this example.
:::

Next, you'll need to configure remoting in your controller config like this:

```yaml
agent_controller:
  z_id:             WEfGMIx-e4
  identity_path:    /home/michael/.zrok/identities/agentremoting.json
```

Restart your controller with this configuration and the agent remoting endpoints will become available.

## Enrolling an Agent

Enrolling an Agent in remoting requires an enabled environment. You can use the `zrok agent enroll` command from an enabled environment to enroll your agent:

```
$ zrok agent enroll

warning! proceeding will allow remote control of your zrok agent!

your agent will accept remote commands from:

https://api-v1.zrok.io

you should only proceed if you understand the implications of this action!

to proceed, type 'yes': yes

agent enrolled with token 'yC9atRbCOskz'

restart your zrok agent to enable remote control

```

When you restart your agent, you will notice the following message in the Agent's log:

```
[   0.001]    INFO zrok/agent.(*Agent).remoteAgent: listening for remote commands at 'yC9atRbCOskz'
```

## The Agent Remoting API

:::note
See the [zrok OpenAPI spec](https://github.com/openziti/zrok/blob/main/specs/zrok.yml) for complete details of `/agent` endpoints.
:::

### Create A Remote Share

:::note
The `apiEndpoint` `http://localhost:18080` is a zrok controller in a local development environment. All of the credentials in this document are local to that instance and already invalid as of publication of this document. It's just an example.
:::

You can call the `/agent/share` endpoint to create a share on a remote Agent through the API:

```
$ curl -H "X-TOKEN: ojF2fna5GKlt" -XPOST -H "Content-Type: application/zrok.v1+json" -d '{"envZId": "qDWmgIxne4", "shareMode": "public", "backendMode": "web", "target": "/home/michael/Repos/nf/zrok"}' http://localhost:18080/api/v1/agent/share | jq
{
  "frontendEndpoints": [
    "http://51bnatug7ua3.zrok.quigley.com:8080"
  ],
  "token": "51bnatug7ua3"
}
```

### Query the Status of the Remote Agent

```
$ curl -H "X-TOKEN: ojF2fna5GKlt" -XPOST -H "Content-Type: application/zrok.v1+json" -d '{"envZId": "qDWmgIxne4"}' http://localhost:18080/api/v1/agent/status | jq
{
  "accesses": null,
  "shares": [
    {
      "backendEndpoint": "/home/michael/Repos/nf/zrok",
      "backendMode": "web",
      "frontendEndpoints": [
        "http://51bnatug7ua3.zrok.quigley.com:8080"
      ],
      "shareMode": "public",
      "token": "51bnatug7ua3"
    }
  ]
}
```

### Remove the Remote Share

```
$ curl -H "X-TOKEN: ojF2fna5GKlt" -XPOST -H "Content-Type: application/zrok.v1+json" -d '{"envZId": "qDWmgIxne4", "token": "51bnatug7ua3"}' http://localhost:18080/api/v1/agent/unshare

$ curl -H "X-TOKEN: ojF2fna5GKlt" -XPOST -H "Content-Type: application/zrok.v1+json" -d '{"envZId": "qDWmgIxne4"}' http://localhost:18080/api/v1/agent/status | jq
{
  "accesses": null,
  "shares": null
}
```

### Creating and Removing Private Access

The `/agent/access` and `/agent/unaccess` endpoints also exist and allow for creating and removing private access frontends remotely.

## Unenrolling an Agent

The `zrok agent unenroll` command will remove all remote control access from an Agent in an environment:

```
$ zrok agent unenroll
SUCCESS: unenrolled agent from 'https://api-v1.zrok.io'
SUCCESS: removed agent-enrollment.json
```

Unenrolling an agent currently enrolled in remoting will result in (ignorable) agent errors. Restart your agent to resume unenrolled operation.