@leverageaiapps/locus-ssh


SSH-mode version of Locus - Forward terminal without ANSI codes. Clean output for AI processing.

Features

- 🚀 Instant Setup - One command to start forwarding your terminal
- 📱 Mobile Access - Access your terminal from any device with a browser
- 🎙️ Voice Input - Built-in voice recognition for hands-free coding
- 🔒 Secure - PIN-protected sessions with automatic IP blocking
- 🌐 No Port Forwarding - Uses Vortex Gateway for secure tunneling
- ⚡ Real-time - WebSocket-based communication for instant feedback
- 🎯 PTY Support - Full terminal emulation with node-pty

Prerequisites

Locus requires Node.js 18 or higher. The Vortex tunnel is built-in and requires no additional dependencies.

Installation

``bash
npm install -g @leverageaiapps/locus
`

Verify Installation:
`bash
locus --version
`

Quick Start

`bash


Start a terminal session

locus

Start with a specific command

locus claude
locus python
locus vim
`

A QR code will appear - scan it with your phone and enter the 6-digit PIN to access your terminal!

Usage

$3

`bash


Start a terminal session

locus

Start with a custom PIN

locus --pin 123456

Start with a machine name

locus --name "My Laptop"

Start a specific command with PIN

locus claude --pin 123456
`

$3

| Option | Short | Description |
|--------|-------|-------------|
| --name | -n | Set a custom machine name |
| --pin | -p | Set a custom 6-digit PIN |
| --debug-asr | | Enable verbose ASR logging |

$3

`bash


Show current configuration


locus config --show
`

How It Works

1. Run locus [command] in your terminal
2. Locus starts a local web server and creates a Vortex tunnel
3. A QR code appears with your unique URL
4. Scan the QR code with your phone
5. Enter the 6-digit PIN to access your terminal
6. Your terminal is now accessible from your mobile device!

$3

To exit Locus, you can:
- Type exit in the terminal (or the command to exit your current program)
- Press Ctrl+C in the terminal where you ran locus
- Close the terminal window

When you see "Terminal session ended.", the session has been successfully closed.

Security

- PIN Protection: Each session requires a 6-digit PIN
- Rate Limiting: Max 10 failed login attempts per IP
- Auto-blocking: IPs are temporarily blocked after too many failures
- Session Cookies: Authentication persists for 24 hours

Troubleshooting

$3

Fix permissions on the node-pty spawn-helper:

`bash


macOS ARM (M1/M2/M3)

chmod +x node_modules/node-pty/prebuilds/darwin-arm64/spawn-helper

macOS Intel

chmod +x node_modules/node-pty/prebuilds/darwin-x64/spawn-helper

Linux x64

chmod +x node_modules/node-pty/prebuilds/linux-x64/spawn-helper
`

$3

If you encounter connection issues, verify the Vortex gateway is accessible:

`bash
curl -I https://vortex.futuretech.social/health
`

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

- Vortex Gateway for secure WebSocket tunneling
- node-pty for PTY support
- xterm.js for terminal emulation in the browser