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

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

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

# View service configuration
sc.exe qc GrantFlowAgent

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

Permissions

# 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

# 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)

cd "C:\Program Files\GrantFlow Agent"

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

Update Agent

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

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

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

# 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

# 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

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

tenantId: "5abfdf65-694b-4c35-9b9b-e65af70c8306"
agentId: "agent-001"
serverUrl: "https://agents.grantflow.cloud"
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

# 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`	443	HTTPS + gRPC	Control plane (ongoing)

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
Check clock synchronization (NTP)

Service Won't Start on Windows

Verify Local Service has 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

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

View today's log for errors:

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:

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

Linux Fix:

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

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

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

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)​

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​

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)

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