Skip to content

Commit a827451

Browse files
authored
feat(tui): add port forwarding support to Gator (#81)
* 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 * fix(tui): fix Ports field invisible due to modal height overflow The modal height calculation used content_height + 3 but block chrome (borders + padding) is 4 rows, not 3. Combined with the 3-row Ports field layout, the input line was clipped to zero height on standard 24-row terminals. Switch Ports to a compact single-line inline layout and fix the chrome arithmetic. * wip: BYOC example with port forwarding and TUI command field fix - Move examples/bring-your-own-container.md into its own directory - Add example Dockerfile and app.py (Python REST API with /hello endpoint) - Rewrite README with full CLI and TUI port-forward workflows - Change TUI Command field default from /bin/bash to empty so custom image entrypoints run without manual clearing * feat(tui): wire up Command field to SSH exec after sandbox creation When a command is specified in the create sandbox modal, the TUI now waits for the sandbox to reach Ready (with the pacman animation), starts any port forwards, then suspends the TUI and executes the command via SSH — matching the CLI's post-creation flow. - Refactor spawn_create_sandbox to poll for Ready inline when ports or command are set, keeping the animation visible throughout - Add start_port_forwards() helper called within the create task - Add handle_exec_command() to suspend TUI and run SSH exec - Remove unused ForwardResult event variant (forwards are now started within the create task, not as a separate event) * fix(tui): fix command exec, forward timeouts, and create modal UX - Fix handle_exec_command to suspend TUI and run SSH attached (matching CLI behavior) so the process stays alive for the session duration - Fix shell_escape double-quoting: escape each word individually - Add ConnectTimeout and 20s spawn timeout to forward SSH so a stalled auth doesn't freeze the create flow forever - Remove dead ForwardResult event variant - Add cluster_name to start_port_forwards for ProxyCommand - Add spacer between Providers and Ports in create modal - Fix Command placeholder: 'runs /bin/bash if empty' (not image entrypoint) - Update BYOC README: document that CMD is replaced by supervisor, command must be passed explicitly, remove TUI-specific sections * fix(sandbox): demote Landlock fallback log from warn to debug The Landlock filesystem sandbox emits a noisy warning when a policy path does not exist (e.g. /app in custom images). Since BestEffort mode intentionally continues without Landlock, demote to debug. * docs: fix BYOC Dockerfile comments for supervisor CMD override --------- Co-authored-by: John Myers <[email protected]>
1 parent 52b48d1 commit a827451

18 files changed

Lines changed: 1147 additions & 471 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)