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

Environment Variables

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

License

MIT