termify-agent

Connect your local machine to Termify and access it from anywhere.

Installation

# Using npm
npm install -g termify-agent

# Using yarn
yarn global add termify-agent

# Using pnpm
pnpm add -g termify-agent

Quick Start

1. Get a Pairing Code

1. Go to Termify Dashboard
2. Navigate to Agents in the sidebar
3. Click Pair New Agent
4. Copy the 6-digit pairing code

2. Pair Your Machine

termify-agent login --code XXXXXX

3. Start the Agent

termify-agent start

That's it! Your machine is now connected to Termify.

Commands

termify-agent login --code <CODE>

Pair this machine with your Termify account using a pairing code.

Options:

• -c, --code <code> - The 6-digit pairing code (required)
• -s, --server <url> - Custom server URL (optional)

termify-agent start

Start the agent and connect to Termify. The agent will:

• Connect to Termify servers via WebSocket
• Listen for terminal creation requests
• Spawn local PTY processes for each terminal
• Stream terminal I/O to/from Termify

Options:

• -f, --foreground - Run in foreground mode (default)

termify-agent status

Show the current status of the agent, including:

• Login status
• Machine information
• Connection details

termify-agent logout

Unpair this machine from Termify. This will:

• Disconnect from Termify servers
• Clear local credentials
• Remove the agent from your dashboard

Security

End-to-End Encryption

All communication between your machine and Termify is encrypted using TLS 1.3. Your terminal data never touches our servers unencrypted.

No Inbound Ports Required

The agent connects outbound to Termify. You don't need to:

• Open any ports on your firewall
• Configure port forwarding
• Expose your machine to the internet

Zero-Trust Architecture

• Each session uses short-lived authentication tokens
• Pairing codes expire after 5 minutes
• Tokens are stored securely in your system's credential store
• Each terminal session is individually authenticated

Data Privacy

• Terminal data is streamed directly, never stored on our servers
• Session metadata is retained for debugging purposes only
• You can disconnect and delete your agent at any time

Running as a Service

macOS (launchd)

# Create a launchd plist
cat > ~/Library/LaunchAgents/com.termify.agent.plist << EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.termify.agent</string>
    <key>ProgramArguments</key>
    <array>
        <string>$(which termify-agent)</string>
        <string>start</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/termify-agent.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/termify-agent.error.log</string>
</dict>
</plist>
EOF

# Load the service
launchctl load ~/Library/LaunchAgents/com.termify.agent.plist

Linux (systemd)

# Create a systemd service file
sudo cat > /etc/systemd/system/termify-agent.service << EOF
[Unit]
Description=Termify Agent
After=network.target

[Service]
Type=simple
User=$USER
ExecStart=$(which termify-agent) start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# Enable and start the service
sudo systemctl enable termify-agent
sudo systemctl start termify-agent

Windows (Task Scheduler)

1. Open Task Scheduler
2. Create a new task
3. Set trigger to "At log on"
4. Set action to run termify-agent start
5. Check "Run whether user is logged on or not"

Troubleshooting

"Not logged in" error

Run termify-agent login --code <CODE> to pair your machine.

"Connection refused" error

• Check your internet connection
• Verify the server URL is correct
• Check if your firewall is blocking outbound connections

Agent disconnects frequently

• Check your network stability
• The agent will automatically reconnect up to 10 times
• Check the logs for more details

Terminal not working

• Ensure your shell is properly configured
• Check if the shell path is correct: echo $SHELL
• Try setting a custom shell: SHELL=/bin/bash termify-agent start

Distill Integration

Termify Agent includes automatic setup for distill, a token-reduction tool for CLI output.

What happens automatically

• During npm install: Distill binary is located, a shim is created at ~/.termify/bin/distill, and config is written to ~/.termify/distill.json
• During termify-agent start: Config and shim are re-validated and repaired if needed
• Global instructions: Distill usage instructions are injected into Claude (~/.claude/CLAUDE.md), Codex (~/.codex/instructions.md), and Gemini (~/.gemini/GEMINI.md)

Configuration

Default config (~/.termify/distill.json):

{
  "primaryHost": "https://termify.justdiego.com/api/ollama",
  "primaryModel": "huihui_ai/qwen3.5-abliterated:2b",
  "timeoutMs": 10000,
  "thinking": false
}

Degraded mode

If the remote Ollama host is unreachable or distill binary is not found, the agent continues normally. Distill instructions still tell AI agents to attempt using distill but gracefully fall back if unavailable.

Managed files

| File | Purpose | |------|---------| | ~/.termify/bin/distill | Stable shim to distill binary | | ~/.termify/distill.json | Distill configuration | | ~/.claude/CLAUDE.md | Distill instruction block (managed) | | ~/.codex/instructions.md | Distill instruction block (managed) | | ~/.gemini/GEMINI.md | Distill instruction block (managed) |

Environment Variables

• TERMIFY_SERVER_URL - Override the default server URL
• TERMIFY_WS_URL - Override the WebSocket URL
• SHELL - Override the default shell

License

MIT