Amp-Thread-ID: https://ampcode.com/threads/T-a6cf4bd2-36d0-4ef8-ada6-a8e2850fcacf Co-authored-by: Amp <amp@ampcode.com>
4 KiB
4 KiB
FleetCode Web Server Setup
FleetCode can run as a web server, making it accessible from any device on your network or over the internet.
Quick Start
# Enter Nix development shell
nix develop
# Install dependencies (first time only)
npm install
# Start the web server
npm run server
The server will start on http://0.0.0.0:3000 by default.
Accessing the Server
Local Access
Open your browser and navigate to:
http://localhost:3000
Network Access
From other devices on your network:
http://<your-machine-ip>:3000
To find your IP address:
# On Linux
ip addr show | grep "inet "
# Or
hostname -I
Remote Access (Internet)
To access FleetCode over the internet, you have several options:
Option 1: Port Forwarding (if you control your router)
- Forward port 3000 on your router to your machine
- Access via your public IP:
http://<your-public-ip>:3000 - Important: Add authentication/security before exposing to internet
Option 2: Tailscale/ZeroTier (recommended for security)
- Install Tailscale or ZeroTier on your machine
- Access via your Tailscale/ZeroTier IP from any device on your network
Option 3: Reverse Proxy (nginx/caddy + Let's Encrypt)
Set up a reverse proxy with HTTPS for secure access
Custom Port
To use a different port:
PORT=8080 npm run server
Architecture
The web server version uses:
- Express - HTTP server
- Socket.IO - Real-time bidirectional communication
- node-pty - Terminal emulation
- xterm.js - Terminal UI in the browser
The same index.html and terminal logic works for both:
- Web mode: Uses Socket.IO instead of Electron IPC
- Desktop mode: Uses Electron IPC for communication
Development
Running the Server
npm run server # Build and start
npm run dev:server # Same as above
Building Only
npm run build # Build TypeScript and CSS
File Structure
FleetCode/
├── server.ts # Web server (Express + Socket.IO)
├── main.ts # Electron main process
├── renderer.ts # Browser/renderer code
├── index.html # UI (works for both modes)
├── dist/
│ ├── server.js # Compiled web server
│ ├── main.js # Compiled Electron main
│ └── styles.css # Compiled Tailwind CSS
Security Considerations
⚠️ Important: The default setup has no authentication!
Before exposing to the internet:
-
Add Authentication
- Implement user login
- Use session tokens
- Consider OAuth/OIDC
-
Use HTTPS
- Set up reverse proxy (nginx/caddy)
- Get SSL certificate (Let's Encrypt)
-
Firewall Rules
- Only allow specific IPs if possible
- Use VPN for remote access
-
Environment Variables
- Don't commit secrets
- Use
.envfiles (not tracked in git)
Troubleshooting
Port Already in Use
# Find what's using the port
sudo lsof -i :3000
# Use a different port
PORT=8080 npm run server
Cannot Connect from Network
- Check firewall:
# On NixOS, check firewall status
sudo iptables -L
# Allow port temporarily
sudo iptables -A INPUT -p tcp --dport 3000 -j ACCEPT
- Verify server is listening on 0.0.0.0 (not 127.0.0.1)
Native Module Errors
If you see errors about node-pty:
# Rebuild for Node.js (not Electron)
npm rebuild node-pty --update-binary
Comparison: Web Server vs Desktop App
| Feature | Web Server | Desktop App |
|---|---|---|
| Remote Access | ✅ Yes | ❌ No |
| Installation | Browser only | Electron required |
| Performance | Network dependent | Native speed |
| Multi-user | Possible (with auth) | Single user |
| Setup | Simple | More complex |
Next Steps
- Add Authentication: Implement user login system
- HTTPS Setup: Configure reverse proxy with SSL
- Multi-user Support: Session isolation per user
- Monitoring: Add logging and metrics
- Docker: Containerize for easy deployment