HostLink

Execute commands on the host machine from inside the OpenClaw container via the HostLink daemon. Provides secure, authenticated remote shell execution over a...

HostLink Skill

Execute commands on the host machine from inside this container.

Quick Reference

# Execute a command on the host
hostlink exec "ls /home/jebadiah"

# Ping the daemon (connection test)
hostlink ping

# With explicit socket/token (if env vars not set)
hostlink -s /run/hostlink/hostlink.sock -k $HOSTLINK_TOKEN exec "echo hello"

# Set working directory
hostlink -w /home/jebadiah exec "pwd"

# Set environment variables
hostlink -e MY_VAR=value exec "echo $MY_VAR"

# With timeout (ms)
hostlink -T 60000 exec "long-running-command"

# JSON output (machine-readable)
hostlink -j exec "ls -la" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['stdout'])"

# List configured targets
hostlink targets

Environment Variables

Set these so you don't need to pass flags every time:

Variable	Purpose	Default
HOSTLINK_SOCKET	Unix socket path	/run/hostlink/hostlink.sock
HOSTLINK_TOKEN	Auth token	(required)
HOSTLINK_TARGET	Target node name	(optional)

Best place to set these: workspace/.env or openclaw.json env.vars section.

Connection Status

Check if hostlinkd is reachable:

hostlink ping
# Expected: [hostname] pong - uptime Xs
# If error: daemon not running or socket not mounted

Common Use Cases

Access host filesystem

hostlink exec "ls /home/jebadiah/projects"
hostlink exec "cat /etc/hostname"

Run host-side GPU/ML tools

hostlink exec "nvidia-smi"
hostlink exec "ollama list"
hostlink exec "ls ~/.cache/huggingface/hub"

Access the Qwen3 merge project

hostlink exec "ls /path/to/qwen3-merge"
hostlink exec "cat /path/to/qwen3-merge/README.md"

Docker management on host

hostlink exec "docker ps"
hostlink exec "docker stats --no-stream"

Exit Codes

Code	Meaning
0	Success
1	Remote command failed (check exit_code in JSON output)
2	Connection failed (daemon unreachable)
3	Authentication failed (wrong token)
5	Timeout
7	Client error (bad args, missing targets file)

Troubleshooting

"Connection failed" / exit 2:

• hostlinkd not running on host: sudo systemctl start hostlinkd
• Socket not mounted: check docker-compose volume mount
• Wrong socket path: check HOSTLINK_SOCKET env var

"Authentication failed" / exit 3:

• Wrong HOSTLINK_TOKEN — must match auth_token in /etc/hostlink/hostlink.conf

"server busy" error:

• Host is at max_concurrent limit — retry shortly

Architecture

Container (you are here)          Host machine
┌─────────────────────┐          ┌──────────────────────────┐
│  hostlink (client)  │◄────────►│  hostlinkd (daemon)      │
│  workspace/bin/     │  Unix    │  /etc/hostlink/           │
│                     │  socket  │  auth_token = <secret>    │
└─────────────────────┘          │  shell = /bin/bash        │
                                 └──────────────────────────┘

See references/setup.md for installation and docker-compose configuration.