Agent Quick Reference

This page provides quick command references for common agent operations on Windows and Linux.

Windows Commands

Installation Directory

Default installation path: C:\Program Files\GrantFlow Agent\

Enrollment

powershell

cd "C:\Program Files\GrantFlow Agent"

.\agent.exe enroll `
  --enrollment-url https://enrollment.grantflow.cloud/enroll `
  --tenant-id YOUR_TENANT_ID `
  --agent-id YOUR_AGENT_ID `
  --token YOUR_ENROLLMENT_TOKEN

Service Management

powershell

cd "C:\Program Files\GrantFlow Agent"

# Install service
.\agent.exe service install

# Start service
.\agent.exe service start

# Stop service
.\agent.exe service stop

# Check status
.\agent.exe service status

# Uninstall service
.\agent.exe service uninstall

Service Configuration

powershell

# View service configuration
sc.exe qc GrantFlowAgent

# Verify service account (should show NT AUTHORITY\LocalService)
sc.exe qc GrantFlowAgent | findstr SERVICE_START_NAME

Permissions

powershell

# Grant Local Service read access to certificates and config
icacls "C:\Program Files\GrantFlow Agent\certs" /grant "NT AUTHORITY\LocalService:(OI)(CI)R" /T
icacls "C:\Program Files\GrantFlow Agent\config" /grant "NT AUTHORITY\LocalService:(OI)(CI)R" /T

Log Files

powershell

# View today's log
Get-Content C:\Windows\Temp\grantflow-agent-$(Get-Date -Format "yyyyMMdd").log

# Tail logs (live view)
Get-Content C:\Windows\Temp\grantflow-agent-$(Get-Date -Format "yyyyMMdd").log -Wait -Tail 50

# View specific date
Get-Content C:\Windows\Temp\grantflow-agent-20251103.log

# Delete logs older than 30 days
Get-ChildItem C:\Windows\Temp\grantflow-agent-*.log |
  Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-30) } |
  Remove-Item

Fix Configuration (Legacy)

powershell

cd "C:\Program Files\GrantFlow Agent"

# Convert relative paths to absolute paths
.\agent.exe fix-config --config .\config\agent-config.yaml

Update Agent

When a newer release is available, agent cards and the agent detail panel display an Update available badge.

powershell

cd "C:\Program Files\GrantFlow Agent"

# 1. Stop service
.\agent.exe service stop

# 2. Replace agent.exe with new version

# 3. Start service
.\agent.exe service start

# 4. Verify
.\agent.exe service status

Linux Commands

Installation Directory

Default installation path: /opt/grantflow-agent/

Enrollment

bash

cd /opt/grantflow-agent

sudo ./agent enroll \
  --enrollment-url https://enrollment.grantflow.cloud/enroll \
  --tenant-id YOUR_TENANT_ID \
  --agent-id YOUR_AGENT_ID \
  --token YOUR_ENROLLMENT_TOKEN

Service Management

bash

cd /opt/grantflow-agent

# Install service
sudo ./agent service install

# Start service
sudo ./agent service start

# Stop service
sudo ./agent service stop

# Check status
sudo ./agent service status

# Uninstall service
sudo ./agent service uninstall

# Alternative: systemctl commands
sudo systemctl start grantflow-agent
sudo systemctl stop grantflow-agent
sudo systemctl status grantflow-agent
sudo systemctl enable grantflow-agent  # Enable on boot

Permissions

bash

# Create dedicated service user
sudo useradd --system --no-create-home --shell /bin/false grantflow-agent

# Set ownership
sudo chown -R grantflow-agent:grantflow-agent /opt/grantflow-agent

Log Files

bash

# View logs
sudo journalctl -u grantflow-agent

# Tail logs (live view)
sudo journalctl -u grantflow-agent -f

# View logs since last boot
sudo journalctl -u grantflow-agent -b

# View logs from specific time range
sudo journalctl -u grantflow-agent --since "2025-11-03 10:00" --until "2025-11-03 12:00"

# View last 100 lines
sudo journalctl -u grantflow-agent -n 100

Update Agent

bash

cd /opt/grantflow-agent

# 1. Stop service
sudo ./agent service stop

# 2. Replace agent binary with new version
sudo cp /path/to/new/agent ./agent
sudo chmod +x ./agent
sudo chown grantflow-agent:grantflow-agent ./agent

# 3. Start service
sudo ./agent service start

# 4. Verify
sudo ./agent service status

Configuration File

Location

Windows: C:\Program Files\GrantFlow Agent\config\agent-config.yaml
Linux: /opt/grantflow-agent/config/agent-config.yaml

Example Configuration

yaml

tenantId: "YOUR_TENANT_ID"
agentId: "agent-001"
serverUrl: "https://agents.grantflow.cloud:8443"
certPath: "C:\\Program Files\\GrantFlow Agent\\certs\\agent-cert.pem"
keyPath: "C:\\Program Files\\GrantFlow Agent\\certs\\agent-key.pem"
caPath: "C:\\Program Files\\GrantFlow Agent\\certs\\ca-chain.pem"

Absolute Paths Required

Certificate paths in the configuration file must be absolute paths, not relative paths. The agent enrollment process automatically creates absolute paths. If you have an old configuration with relative paths, use the fix-config command to convert them.

Certificate Files

Location

Windows: C:\Program Files\GrantFlow Agent\certs\
Linux: /opt/grantflow-agent/certs/

Files Created During Enrollment

agent-cert.pem - Agent mTLS certificate (issued by GrantFlow)
agent-key.pem - Agent private key
ca-chain.pem - CA certificate chain for verifying control plane

Certificate Rotation

Certificates are automatically rotated by the agent before expiration. No manual intervention is required.

Verify Certificate

bash

# View certificate details
openssl x509 -in agent-cert.pem -text -noout

# Check expiration date
openssl x509 -in agent-cert.pem -noout -enddate

Network Requirements

Outbound Connections (Agent → Cloud)

Destination	Port	Protocol	Purpose
`enrollment.grantflow.cloud`	443	HTTPS	Agent enrollment (one-time)
`agents.grantflow.cloud`	8443	HTTPS + gRPC	Control plane (ongoing)
`agents.grantflow.cloud`	8444–8453	TCP (TLS)	Session relay shards — tunnel agent hosts only

Tunnel Agent Hosts

A tunnel agent is an agent enrolled into a network zone to carry browser sessions to servers in that zone. On every host that runs a tunnel agent, allow:

Outbound TCP 8443–8453 from this host to agents.grantflow.cloud. Nothing inbound is needed.

Port 8443 is the control channel; 8444–8453 are the relay shards. GrantFlow picks a relay shard for each session and automatically fails over to another shard if one is unreachable, so open the whole range. You do not assign a relay shard per zone.

AD and Entra agents that are not tunnel agents still need only TCP/8443. Domain controllers need no new rule.

Agent version

Tunnel agents must run agent version 0.3.5 or later. Older agents cannot open sessions. Each agent accepts only relay addresses listed in its signed allowlist, and older agents cannot read the current allowlist format.

On-Premises Connections (Agent → Domain Controllers)

Destination	Port	Protocol	Purpose
Domain Controllers	389	LDAP	Directory operations (unencrypted)
Domain Controllers	636	LDAPS	Directory operations (TLS encrypted)

Recommended

Use LDAPS (port 636) for production environments to encrypt all communication with domain controllers.

Common Issues

Agent Shows Offline

Check service status: .\agent.exe service status (Windows) or sudo systemctl status grantflow-agent (Linux)
View logs for errors
Test network connectivity: curl -v https://agents.grantflow.cloud:8443
Check clock synchronization (NTP)

Service Won't Start on Windows

Verify Local Service has permissions:

powershell

icacls "C:\Program Files\GrantFlow Agent\certs" /grant "NT AUTHORITY\LocalService:(OI)(CI)R" /T
icacls "C:\Program Files\GrantFlow Agent\config" /grant "NT AUTHORITY\LocalService:(OI)(CI)R" /T

Check service account configuration:
powershell
```
sc.exe qc GrantFlowAgent
```

View today's log for errors:

powershell

Get-Content C:\Windows\Temp\grantflow-agent-$(Get-Date -Format "yyyyMMdd").log

Certificate File Not Found

Symptom: Log shows FATAL: Certificate file not found

Windows Fix:

powershell

cd "C:\Program Files\GrantFlow Agent"
.\agent.exe fix-config --config .\config\agent-config.yaml

Linux Fix:

bash

cd /opt/grantflow-agent
sudo ./agent fix-config --config ./config/agent-config.yaml

Enrollment Token Expired

Symptom: Enrollment fails with token validation error

Fix:

Go to GrantFlow Admin → Connectors → Active Directory → Agents
Click "Enroll Agent" to generate a new token
Copy the new token and run enrollment immediately (tokens expire after 1 hour)

Re-enrollment Process

If you need to reset the agent completely:

Windows

powershell

cd "C:\Program Files\GrantFlow Agent"

# 1. Stop and uninstall
.\agent.exe service stop
.\agent.exe service uninstall

# 2. Remove old certificates and config
Remove-Item "C:\Program Files\GrantFlow Agent\certs\*" -Force
Remove-Item "C:\Program Files\GrantFlow Agent\config\agent-config.yaml" -Force

# 3. Enroll with new token
.\agent.exe enroll `
  --enrollment-url https://enrollment.grantflow.cloud/enroll `
  --tenant-id YOUR_TENANT_ID `
  --agent-id YOUR_AGENT_ID `
  --token YOUR_NEW_ENROLLMENT_TOKEN

# 4. Grant permissions
icacls "C:\Program Files\GrantFlow Agent\certs" /grant "NT AUTHORITY\LocalService:(OI)(CI)R" /T
icacls "C:\Program Files\GrantFlow Agent\config" /grant "NT AUTHORITY\LocalService:(OI)(CI)R" /T

# 5. Install and start service
.\agent.exe service install
.\agent.exe service start

Linux

bash

cd /opt/grantflow-agent

# 1. Stop and uninstall
sudo ./agent service stop
sudo ./agent service uninstall

# 2. Remove old certificates and config
sudo rm -f certs/*
sudo rm -f config/agent-config.yaml

# 3. Enroll with new token
sudo ./agent enroll \
  --enrollment-url https://enrollment.grantflow.cloud/enroll \
  --tenant-id YOUR_TENANT_ID \
  --agent-id YOUR_AGENT_ID \
  --token YOUR_NEW_ENROLLMENT_TOKEN

# 4. Set ownership
sudo chown -R grantflow-agent:grantflow-agent /opt/grantflow-agent

# 5. Install and start service
sudo ./agent service install
sudo ./agent service start

Agent Quick Reference ​

Windows Commands ​

Installation Directory ​

Enrollment ​

Service Management ​

Service Configuration ​

Permissions ​

Log Files ​

Fix Configuration (Legacy) ​

Update Agent ​

Linux Commands ​

Installation Directory ​

Enrollment ​

Service Management ​

Permissions ​

Log Files ​

Update Agent ​

Configuration File ​

Location ​

Example Configuration ​

Certificate Files ​

Location ​

Files Created During Enrollment ​

Certificate Rotation ​

Verify Certificate ​

Network Requirements ​

Outbound Connections (Agent → Cloud) ​

Tunnel Agent Hosts ​

On-Premises Connections (Agent → Domain Controllers) ​

Common Issues ​

Agent Shows Offline ​

Service Won't Start on Windows ​

Certificate File Not Found ​

Enrollment Token Expired ​

Re-enrollment Process ​

Windows ​

Linux ​

See Also ​

Agent Quick Reference

Windows Commands

Installation Directory

Enrollment

Service Management

Service Configuration

Permissions

Log Files

Fix Configuration (Legacy)

Update Agent

Linux Commands

Installation Directory

Enrollment

Service Management

Permissions

Log Files

Update Agent

Configuration File

Location

Example Configuration

Certificate Files

Location

Files Created During Enrollment

Certificate Rotation

Verify Certificate

Network Requirements

Outbound Connections (Agent → Cloud)

Tunnel Agent Hosts

On-Premises Connections (Agent → Domain Controllers)

Common Issues

Agent Shows Offline

Service Won't Start on Windows

Certificate File Not Found

Enrollment Token Expired

Re-enrollment Process

Windows

Linux

See Also