Remote Access Guide¶

Access your agentwatch web viewer from anywhere with secure tunneling.

Overview¶

agentwatch supports two methods for remote access:

Method	Setup	Best For
agentwatch.sh tunnel	Automatic via setup wizard	Most users
Manual Cloudflare Tunnel	Self-managed configuration	Full control

Both methods provide secure HTTPS access without exposing ports.

agentwatch.sh Tunnel (Recommended)¶

The easiest way to get remote access.

How It Works¶

agentwatch provisions a subdomain at *.agentwatch.sh
A Cloudflare Tunnel connects your local daemon to the subdomain
Traffic is encrypted end-to-end

Setup¶

Step 1: Get a Device Token¶

Visit the agentwatch dashboard to create a device token.

Step 2: Run Setup¶

agentwatch setup --token <YOUR_DEVICE_TOKEN>

Or add it to an existing installation:

agentwatch config set token <YOUR_DEVICE_TOKEN>
agentwatch restart

Step 3: Check Your URL¶

agentwatch status

Look for the tunnel URL (e.g., https://mydevice.agentwatch.sh/).

Configuration¶

Tunnel settings in config.yaml:

tunnel:
  enabled: true

The device token is stored securely at ~/.config/agentwatch/tokens/device.

Multiple Tunnels¶

If you have multiple devices, each gets a unique subdomain. List them:

agentwatch tunnels

Manual Cloudflare Tunnel¶

For users who want full control over their tunnel configuration.

Prerequisites¶

A Cloudflare account
A domain managed by Cloudflare
cloudflared installed

Step 1: Install cloudflared¶

macOSLinux

brew install cloudflared

# Debian/Ubuntu
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb -o cloudflared.deb
sudo dpkg -i cloudflared.deb

# Or download binary
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
chmod +x cloudflared
sudo mv cloudflared /usr/local/bin/

Step 2: Authenticate¶

cloudflared tunnel login

This opens a browser to authorize cloudflared with your Cloudflare account.

Step 3: Create a Tunnel¶

cloudflared tunnel create agentwatch

Note the tunnel ID and credentials file path.

Step 4: Create Tunnel Config¶

Create ~/.cloudflared/config-agentwatch.yml:

tunnel: <TUNNEL_ID>
credentials-file: ~/.cloudflared/<TUNNEL_ID>.json

ingress:
  - hostname: agentwatch.yourdomain.com
    service: https://localhost:8081
    originRequest:
      noTLSVerify: true   # Accept self-signed cert
  - service: http_status:404

Step 5: Add DNS Route¶

cloudflared tunnel route dns <TUNNEL_ID> agentwatch.yourdomain.com

Step 6: Configure agentwatch¶

Update ~/.config/agentwatch/config.yaml:

cloudflare:
  enabled: true
  config_file: ~/.cloudflared/config-agentwatch.yml

Step 7: Restart¶

agentwatch restart

Verify¶

curl https://agentwatch.yourdomain.com/health
# Expected: {"s":"ok", ...}

Security Considerations¶

Authentication¶

Both tunnel methods preserve agentwatch's OS authentication:

Users must log in with system credentials
Only the daemon user can authenticate (by default)
Sessions expire after 24 hours

Encryption¶

Local: HTTPS with self-signed certificate
Remote: HTTPS with Cloudflare-issued certificate
Tunnel: Encrypted connection to Cloudflare edge

Access Control¶

For additional security:

Cloudflare Access (Manual Tunnel)¶

Add Cloudflare Access rules to require additional authentication:

Go to Cloudflare Zero Trust dashboard
Create an Access application for your hostname
Add authentication rules (SSO, email, etc.)

Firewall Rules¶

The daemon only listens on localhost (127.0.0.1) by default. Change this only if needed:

web_viewer:
  host: 0.0.0.0    # Listen on all interfaces (use with caution)

Troubleshooting¶

Tunnel Not Connecting¶

Check daemon status:
```
agentwatch status
```
Check tunnel process:
```
ps aux | grep cloudflared
```
Check logs:
```
agentwatch logs | grep -i tunnel
```

Can't Reach Remote URL¶

Verify DNS:
```
dig your-subdomain.agentwatch.sh
```
Test locally first:
```
curl -sk https://localhost:8081/health
```
Check Cloudflare status:
Visit cloudflare.com/system-status

Authentication Fails Remotely¶

The same credentials work locally and remotely. If remote fails:

Try logging in locally first
Check for special characters in password
Verify the daemon user matches your login

Slow Connection¶

Tunnels add latency. For better performance:

Choose a nearby Cloudflare data center
Reduce terminal capture quality in web viewer settings
Consider lower capture intervals in config

Disabling Remote Access¶

agentwatch.sh Tunnel¶

# Remove token
rm ~/.config/agentwatch/tokens/device

# Edit config to disable tunnel
# tunnel:
#   enabled: false

agentwatch restart

Manual Cloudflare Tunnel¶

# config.yaml
cloudflare:
  enabled: false

Then restart:

agentwatch restart

Using Both Methods¶

You can't use both agentwatch.sh tunnel and manual Cloudflare tunnel simultaneously. Choose one method.

If you have the agentwatch.sh tunnel enabled and also want manual control, disable the automatic tunnel:

tunnel:
  enabled: false

cloudflare:
  enabled: true
  config_file: ~/.cloudflared/config-agentwatch.yml