Skip to content

Commit e506d8c

Browse files
committed
feat(tui): add port forwarding support to Gator (#80)
Extract forward PID management, resolve_ssh_gateway, and shell_escape from navigator-cli into navigator-core::forward as a shared module. Add a Ports field to the TUI create sandbox modal, a NOTES column to the sandbox table, and a Forwards row to the sandbox detail view. On creation with ports, Gator polls for Ready state then spawns background SSH tunnels. Forward cleanup runs automatically on sandbox delete. Closes #80
1 parent 52b48d1 commit e506d8c

14 files changed

Lines changed: 783 additions & 374 deletions

File tree

‎Cargo.lock‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎architecture/gator.md‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,8 @@ The Sandboxes view shows a table of all sandboxes in the cluster:
6868
| STATUS | Current phase, color-coded (see below) |
6969
| AGE | Time since creation (e.g., `45s`, `12m`, `3h 20m`, `2d 5h`) |
7070
| IMAGE | Container image the sandbox is running |
71+
| PROVIDERS | Provider names attached to the sandbox |
72+
| NOTES | General-purpose metadata (e.g., `fwd:8080,3000` for forwarded ports) |
7173

7274
Status colors tell you the sandbox state at a glance:
7375

@@ -124,11 +126,23 @@ Gator uses a dark terminal theme based on the NVIDIA brand palette:
124126

125127
The title bar uses white text on an Everglade background to visually anchor the top of the screen.
126128

129+
## Port Forwarding
130+
131+
Gator supports creating sandboxes with port forwarding directly from the create modal. When creating a sandbox, you can specify ports to forward in the **Ports** field (comma-separated, e.g., `8080,3000`). After the sandbox reaches `Ready` state, Gator automatically spawns background SSH tunnels (`ssh -N -f -L <port>:127.0.0.1:<port>`) for each specified port.
132+
133+
Forwarded ports are displayed in the **NOTES** column of the sandbox table as `fwd:8080,3000` and in the **Forwards** row of the sandbox detail view.
134+
135+
Port forwarding lifecycle:
136+
- **On create**: Gator polls for sandbox readiness (up to 30 attempts at 2-second intervals), then spawns SSH tunnels.
137+
- **On delete**: Any active forwards for the sandbox are automatically stopped before deletion.
138+
- **PID tracking**: Forward PIDs are stored in `~/.config/nemoclaw/forwards/<name>-<port>.pid`, shared with the CLI.
139+
140+
The forwarding implementation lives in `navigator-core::forward`, shared between the CLI and TUI.
141+
127142
## What is Not Yet Available
128143

129144
Gator is in its initial phase. The following features are planned but not yet implemented:
130145

131-
- **Sandbox operations** — creating, connecting to (SSH), deleting, and viewing logs for sandboxes.
132146
- **Inference and provider views** — browsing inference routes and provider configurations.
133147
- **Help overlay** — the `?` key is shown in the nav bar but does not open a help screen yet.
134148
- **Command bar autocomplete** — the command bar accepts text but does not offer suggestions.
@@ -140,4 +154,4 @@ See the [Gator design plan](plans/gator-tui.md) for the full roadmap, including
140154

141155
The TUI lives in `crates/navigator-tui/`, a separate workspace crate. The CLI crate (`crates/navigator-cli/`) depends on it and launches it via the `Gator` command variant in the `Commands` enum. This keeps TUI-specific dependencies (ratatui, crossterm) out of the CLI when not in use.
142156

143-
The `navigator-tui` crate depends on `navigator-core` for protobuf types and the gRPC client — it communicates with the gateway over the same gRPC channel the CLI uses.
157+
The `navigator-tui` crate depends on `navigator-core` for protobuf types, the gRPC client, and shared utilities (e.g., `navigator_core::forward` for port forwarding PID management) — it communicates with the gateway over the same gRPC channel the CLI uses.

‎architecture/sandbox-connect.md‎

Lines changed: 34 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -170,6 +170,36 @@ on the host are forwarded to `127.0.0.1:<port>` inside the sandbox.
170170
when no trailing command is provided.
171171
- `ncl sandbox delete` auto-stops any active forwards for the deleted sandbox.
172172

173+
#### TUI (Gator)
174+
175+
The TUI (`crates/navigator-tui/`) supports port forwarding through the create sandbox modal. Users
176+
specify comma-separated ports in the **Ports** field. After sandbox creation:
177+
178+
1. Gator polls for `Ready` state (up to 30 attempts at 2-second intervals).
179+
2. Creates an SSH session via `CreateSshSession` gRPC.
180+
3. Spawns background SSH tunnels (`ssh -N -f -L <port>:127.0.0.1:<port>`) for each port.
181+
4. Sends a `ForwardResult` event back to the main loop with the outcome.
182+
183+
Active forwards are displayed in the sandbox table's NOTES column (e.g., `fwd:8080,3000`) and in
184+
the sandbox detail view's Forwards row.
185+
186+
When deleting a sandbox, Gator calls `stop_forwards_for_sandbox()` before sending the delete
187+
request. PID tracking uses the same `~/.config/nemoclaw/forwards/` directory as the CLI.
188+
189+
#### Shared forward module
190+
191+
**File**: `crates/navigator-core/src/forward.rs`
192+
193+
Port forwarding PID management and SSH utility functions are shared between the CLI and TUI:
194+
195+
- `forward_dir()` -- returns `~/.config/nemoclaw/forwards/`, creating it if needed
196+
- `save_forward_pid()` / `read_forward_pid()` / `remove_forward_pid()` -- PID file I/O
197+
- `list_forwards()` -- lists all active forwards from PID files
198+
- `stop_forward()` / `stop_forwards_for_sandbox()` -- kills forwarding processes by PID
199+
- `resolve_ssh_gateway()` -- loopback gateway resolution (see Gateway Loopback Resolution)
200+
- `shell_escape()` -- safe shell argument escaping for SSH commands
201+
- `build_sandbox_notes()` -- builds notes strings (e.g., `fwd:8080,3000`) from active forwards
202+
173203
#### Supervisor `direct-tcpip` handling
174204

175205
The sandbox SSH server (`crates/navigator-sandbox/src/ssh.rs`) implements
@@ -473,12 +503,14 @@ The gateway builds the remote command by shell-escaping arguments, prepending so
473503

474504
## Gateway Loopback Resolution
475505

476-
**File**: `crates/navigator-cli/src/ssh.rs` -- `resolve_ssh_gateway()`
506+
**File**: `crates/navigator-core/src/forward.rs` -- `resolve_ssh_gateway()`
477507

478-
When the gateway returns a loopback address (`127.0.0.1`, `0.0.0.0`, `localhost`, or `::1`), the CLI overrides it with the host from the cluster endpoint URL. This handles the common case where the gateway defaults to `127.0.0.1` but the cluster is running on a remote machine.
508+
When the gateway returns a loopback address (`127.0.0.1`, `0.0.0.0`, `localhost`, or `::1`), the client overrides it with the host from the cluster endpoint URL. This handles the common case where the gateway defaults to `127.0.0.1` but the cluster is running on a remote machine.
479509

480510
The override only applies if the cluster endpoint itself is not also a loopback address. If both are loopback, the original address is kept.
481511

512+
This function is shared between the CLI and TUI via the `navigator-core::forward` module.
513+
482514
## Authentication and Security Model
483515

484516
### Layered authentication

‎crates/navigator-cli/src/run.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,11 +45,11 @@ use tonic::{Code, transport::Channel};
4545

4646
// Re-export SSH functions for backward compatibility
4747
pub use crate::ssh::print_ssh_config;
48-
pub use crate::ssh::{list_forwards, stop_forward, stop_forwards_for_sandbox};
4948
pub use crate::ssh::{
5049
sandbox_connect, sandbox_exec, sandbox_forward, sandbox_ssh_proxy, sandbox_ssh_proxy_by_name,
5150
sandbox_sync_down, sandbox_sync_up, sandbox_sync_up_files,
5251
};
52+
pub use navigator_core::forward::{list_forwards, stop_forward, stop_forwards_for_sandbox};
5353

5454
/// Convert a sandbox phase integer to a human-readable string.
5555
fn phase_name(phase: i32) -> &'static str {

0 commit comments

Comments
 (0)