Implement local port forwarding

README.md

@@ -75,6 +75,11 @@ sbx run my-sbx --mount /home/me/src/tooling:/workspace/tooling
 # Disable automatic OAuth callback forwarding.
 sbx run my-sbx --no-auth-port
 
+# Temporarily forward a running guest web server until Ctrl-C.
+sbx network forward my-sbx 3000
+sbx network forward 8080:3000
+sbx network forward 0.0.0.0:3000:3000
+
 # Keep the VM running after the agent/shell exits.
 sbx run my-sbx --keep-running
 sbx shell my-sbx --keep-running
@@ -111,6 +116,7 @@ sbx run my-sbx --agent claude
 | `shell [NAME]`                   | Open a shell in a sandbox.                                                               |
 | `ls`                             | List running sandboxes. Use `ls -a` / `ls --all` to include stopped ones.                |
 | `network status [NAME]`          | Expert helper: show sandbox networking and auth callback tunnel status.                  |
+| `network forward [NAME] SPEC`    | Temporarily forward a host TCP port to a running sandbox until Ctrl-C.                   |
 | `network auth-port [NAME]`       | Expert helper: manually expose the OAuth callback port for an already-running sandbox.   |
 | `network close-auth-port [NAME]` | Expert helper: close the tracked OAuth callback tunnel.                                  |
 | `image build-debian`             | Advanced helper: build a local Debian/Pi image, optionally with `--with-docker`.         |
@@ -144,6 +150,13 @@ image = "~/.smolvm/images/debian-sbx"
 run_user = "agent"
 ```
 
+Configure durable TCP forwards applied when the VM starts:
+
+```toml
+[sbx]
+port_forwards = ["3000", "8080:3000"]
+```
+
 Build with Docker support:
 
 ```bash

docs/network-command-roadmap.md

@@ -10,6 +10,23 @@ sbx network ...
 
 ## Current commands
 
+### `sbx network forward [NAME] SPEC`
+
+Forwards a host TCP port to a running sandbox in the foreground. Press Ctrl-C to stop.
+
+```bash
+sbx network forward 3000
+sbx network forward 8080:3000
+sbx network forward 0.0.0.0:3000:3000
+```
+
+Configured forwards live in `.sbx.toml` and are applied when the VM starts:
+
+```toml
+[sbx]
+port_forwards = ["3000", "8080:3000"]
+```
+
 ### `sbx network status NAME`
 
 Shows networking details and auth callback tunnel state for one sandbox.

pyproject.toml

@@ -7,12 +7,11 @@ name = "sbx"
 version = "0.2.4.dev0"
 description = "Run Pi/Claude/Codex coding agents in disposable SmolVM sandboxes."
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.12"
 license = "Apache-2.0"
 authors = [{ name = "sbx contributors" }]
 dependencies = [
   "smolvm==0.0.26",
-  "tomli>=2.4.1; python_version < '3.11'",
 ]
 
 [project.optional-dependencies]
@@ -31,7 +30,7 @@ packages = ["src/sbx"]
 
 [tool.ruff]
 line-length = 100
-target-version = "py310"
+target-version = "py312"
 src = ["src", "tests"]
 
 [tool.ruff.lint]

sbx.toml.example

@@ -17,3 +17,6 @@ stop_on_exit = false
 copy_host_credentials = false
 env = []
 git_config = true
+
+# Optional host-to-guest TCP forwards, applied when the VM starts.
+# port_forwards = ["3000", "8080:3000", "0.0.0.0:3000:3000"]