https://github.com/y0sif/ferlay
Start and manage Claude Code sessions from your phone.
https://github.com/y0sif/ferlay
ai-agent claude-code cli developer-tools flutter mobile remote-control rust session-management websocket
Last synced: about 2 months ago
JSON representation
Start and manage Claude Code sessions from your phone.
- Host: GitHub
- URL: https://github.com/y0sif/ferlay
- Owner: y0sif
- License: mit
- Created: 2026-03-22T04:06:05.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-29T02:40:36.000Z (3 months ago)
- Last Synced: 2026-03-29T04:30:18.994Z (3 months ago)
- Topics: ai-agent, claude-code, cli, developer-tools, flutter, mobile, remote-control, rust, session-management, websocket
- Language: Dart
- Homepage: https://ferlay.dev
- Size: 6.34 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
---
**Start, manage, and approve Claude Code sessions from your phone.** Spin up coding sessions, approve tool-use prompts, and monitor progress - all from anywhere.
One command to install, pair, and go.
## Install
### Linux / macOS
```sh
curl -sSL https://ferlay.dev/install.sh | sh
```
### Windows
```powershell
irm https://ferlay.dev/install.ps1 | iex
```
The installer downloads the daemon, then runs `ferlay setup` which walks you through:
1. **Relay configuration** - uses the hosted relay by default, or enter your own URL
2. **Pairing** - displays a QR code, scan it with the Ferlay app
3. **Background service** - installs and starts the daemon (systemd on Linux, launchd on macOS, Task Scheduler on Windows)
After setup, the daemon runs in the background and starts automatically on login. That's it.
Other install methods (AUR, Homebrew, from source)
### Arch Linux (AUR)
```sh
yay -S ferlay-bin
```
### Homebrew (macOS)
```sh
brew install y0sif/tap/ferlay
```
### From source
```sh
cargo install --path daemon
ferlay setup
```
## Get the App
| Platform | Link |
|----------|------|
| Android (APK) | [Latest release](https://github.com/y0sif/ferlay/releases/latest) |
| iOS | Coming soon |
> **Google Play**: Ferlay is currently in internal testing on the Play Store. To help get it published, we need testers to opt in. If you'd like to help, send your Gmail address to [y0sif](https://github.com/y0sif) (open an issue or DM) and you'll receive an invite link to join the test.
---
## How It Works
```
Phone App <--> Relay Server <--> Daemon <--> Claude Code
(relay.ferlay.dev) (your machine)
```
1. **Daemon** runs on your computer, manages Claude Code sessions
2. **Relay** routes encrypted messages between your phone and daemon
3. **App** on your phone - scan QR to pair, tap to start sessions
All communication is **end-to-end encrypted** (X25519 + AES-256-GCM). The relay only forwards opaque ciphertext.
---
Self-hosted relay
Run your own relay for full infrastructure control. No database, no external dependencies.
```sh
# Docker
docker run -d -p 8080:8080 ghcr.io/y0sif/ferlay-relay:latest
# Or from source
cargo run -p ferlay-relay
```
Point your daemon at it:
```sh
ferlay config set relay-url wss://your-relay.example.com/ws
```
For production TLS, the `deploy/` directory has ready-made configs for Cloudflare Tunnel, Caddy (auto-TLS), and nginx.
Local mode
For development or same-network use. Runs a local relay and daemon together, no external server.
```sh
ferlay daemon --local
```
Or use the dev script:
```sh
./scripts/ferlay-local.sh # Linux/macOS
./scripts/ferlay-local.ps1 # Windows
```
---
## CLI Reference
```
ferlay setup Interactive setup (relay, pairing, auto-start)
ferlay daemon [--local] [--relay ] [--re-pair] Start the daemon in foreground
ferlay pair Re-pair with a new phone
ferlay status Check daemon health
ferlay config show Show current configuration
ferlay config set relay-url Change relay server
ferlay config reset Reset to defaults
```
---
## Project Structure
```
ferlay/
├── daemon/ Rust CLI daemon - manages Claude Code sessions
├── relay/ Rust WebSocket relay server
├── app/ Flutter mobile app (Android, iOS)
├── shared/ Shared message types and protocol definitions
├── scripts/ Install scripts (Linux, macOS, Windows)
└── deploy/ Service files and deployment configs
```
---
## Development
```sh
cargo build # Build all crates
cargo test # Run tests
cargo clippy --all-targets -- -D warnings # Lint
RUST_LOG=ferlay_relay=debug cargo run -p ferlay-relay # Run relay locally
./scripts/ferlay-local.sh # Run daemon + local relay
```
```sh
cd app && flutter pub get && flutter run # Run the Flutter app
```
---
## Contributing
The biggest ways to help right now:
1. **Test the daemon** on your OS - Linux distros, macOS versions, Windows. Report what works and what doesn't.
2. **Test the app** - pairing flow, session management, connection stability.
3. **Bug reports** - if pairing fails, sessions don't start, or connections drop, open an issue.
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
---
## License
[MIT](LICENSE)