Add `databricks sandbox port-forward` by jaecho-db · Pull Request #7395 · databricks/cli

jaecho-db · 2026-11-07T06:58:23Z

Changes

Add databricks sandbox port-forward [sandbox-id] -L LOCAL:REMOTE.... Each -L serves http://127.0.0.1:LOCAL and relays HTTP and WebSocket traffic to the app on sandbox port REMOTE through the workspace's /sandbox-proxy/sandboxes/<id>/ports/<port>/ route, authenticated as the caller. Without an ID it uses the default sandbox.

Every forwarded request carries the caller's credentials, so a forward:

binds to loopback and only accepts requests addressed to localhost;
refuses cross-site browser requests (by Origin and Sec-Fetch-Site), so neither a DNS-rebinding page nor a page on another site can use it, including over WebSockets;
replaces the local client's Authorization and X-Databricks-* headers with the CLI's;
refuses paths with . or .. segments, which the workspace would resolve outside the port route.

Remote ports outside 10000-65535 are rejected up front, and a stopped sandbox is started before forwarding, like sandbox ssh.

Replaces #7367, which was opened from a fork.

Why

Users can open apps running in their sandbox without setting up SSH. This is the CLI counterpart of the Python SDK's SandboxExt.port_forward.

Tests

Unit tests for -L parsing, the request rewrite and its guards, WebSocket relay, auth failures, and sandbox resolution. Acceptance tests for argument and lookup errors.
Manually against a staging workspace: HTTP and WebSocket traffic, credential stripping, refused ports and hosts, an unknown sandbox, and Ctrl-C.

This pull request and its description were written by Isaac.

Forward local ports to apps in a sandbox: each -L LOCAL:REMOTE serves http://127.0.0.1:LOCAL and relays HTTP and WebSocket traffic through the workspace's /sandbox-proxy/sandboxes/<id>/ports/<port>/ route with the caller's credentials. Forwards accept only localhost-addressed requests and refuse dot-segment paths, so neither a DNS-rebinding page nor a crafted path can use those credentials outside the port route. Co-authored-by: Isaac <no-reply@databricks.com>

…oxes Refuse browser requests from other sites (Origin, Sec-Fetch-Site) so a web page can't use a forward, including over WebSockets. Reject remote ports outside 10000-65535 at parse time, start a stopped sandbox before forwarding like `sandbox ssh`, also serve the IPv6 loopback, and keep net/http's error reports in the debug log. Co-authored-by: Isaac <no-reply@databricks.com>

The sandbox command group is now visible as a Beta feature, so the new subcommand belongs in the release notes. Co-authored-by: Isaac <no-reply@databricks.com>

github-actions · 2026-11-07T07:04:49Z

Commit: 1e4492810 | Workflow run

Regression test report

Selected 3 changed tests (limit=20, 0 not selected)

3 tests: regression=3 unreleased=0 coverage=0 failing=0

test	branch	main (`21db1be`)	latest (v1.24.0)
TestAccept/cmd/sandbox/port-forward/invalid-forward	✅	❌	❌
TestAccept/cmd/sandbox/port-forward/no-default	✅	❌	❌
TestAccept/cmd/sandbox/port-forward/not-found	✅	❌	❌

TestAccept/cmd/sandbox/port-forward/invalid-forward: branch ✅ | main (21db1be) ❌ | latest (v1.24.0) ❌

main (21db1be):

acceptance_test.go:1345: Diff:
        --- cmd/sandbox/port-forward/invalid-forward/output.txt
        +++ /tmp/TestAcceptcmdsandboxport-forwardinvalid-forward3201517177/002/output.txt
        @@ -1,3 +1,108 @@
        -Error: invalid -L "8080": expected LOCAL:REMOTE ports, e.g. 8080:10080
        -Error: invalid -L "8080:8080": remote port must be between 10000 and 65535
        -Error: required flag(s) "forward" not set
        +Error: unknown shorthand flag: 'L' in -L
        +
        +Usage:
        +  databricks sandbox [command]
        +
        +Available Commands:
        +  config      Configure a Sandbox's name and auto-stop policy
        +  create      Create a new Sandbox environment
        +  default     Set the default Sandbox for SSH
        +  delete      Delete a Sandbox environment
        +  list        List your Sandbox environments
        +  register    Register this machine for sandbox SSH access
        +  ssh         SSH into a Sandbox environment
        +  ssh-key     Manage SSH keys registered with the sandbox service
        +  start       Start a stopped Sandbox environment
        +  status      Show Sandbox environment status
        +  stop        Stop a running Sandbox environment
        +
        +Flags:
        +  -h, --help   help for sandbox
        +
        +Global Flags:
        +      --debug            enable debug logging
        +  -o, --output type      output type: text or json (default text)
        +  -p, --profile string   ~/.databrickscfg profile
        +  -t, --target string    bundle target to use (if applicable)
        +
        +Use "databricks sandbox [command] --help" for more information about a command.
        +
        +Error: unknown shorthand flag: 'L' in -L
        +
        +Usage:
        +  databricks sandbox [command]
        +
        +Available Commands:
        +  config      Configure a Sandbox's name and auto-stop policy
        +  create      Create a new Sandbox environment
        +  default     Set the default Sandbox for SSH
        +  delete      Delete a Sandbox environment
        +  list        List your Sandbox environments
        +  register    Register this machine for sandbox SSH access
        +  ssh         SSH into a Sandbox environment
        +  ssh-key     Manage SSH keys registered with the sandbox service
        +  start       Start a stopped Sandbox environment
        +  status      Show Sandbox environment status
        +  stop        Stop a running Sandbox environment
        +
        +Flags:
        +  -h, --help   help for sandbox
        +
        +Global Flags:
        +      --debug            enable debug logging
        +  -o, --output type      output type: text or json (default text)
        +  -p, --profile string   ~/.databrickscfg profile
        +  -t, --target string    bundle target to use (if applicable)
        +
        +Use "databricks sandbox [command] --help" for more information about a command.
        +
        +Manage Databricks Sandbox environments.
        +
        +Sandbox provides SSH-accessible development environments backed by
        +microVM isolation. Each sandbox is a personal sandbox with pre-installed
        +tooling (Python, Node.js, Rust, Databricks CLI) and persistent storage.
        +
        +Getting started:
        +  databricks auth login --host https://...   # authenticate to a Databricks workspace
        +  databricks sandbox register                # generate and register an SSH key
        +  databricks sandbox create                  # provision a sandbox (becomes your default)
        +  databricks sandbox ssh                     # SSH to your default sandbox
        +
        +Common workflows:
        +  databricks sandbox ssh                     # SSH to your default sandbox
        +  databricks sandbox ssh my-project          # SSH to a named sandbox
        +  databricks sandbox list                    # list your sandboxes
        +  databricks sandbox create                  # create a new sandbox
        +  databricks sandbox delete my-project       # delete a sandbox
        +  databricks sandbox status my-project       # show sandbox status
        +
        +Usage:
        +  databricks sandbox [command]
        +
        +Available Commands:
        +  config      Configure a Sandbox's name and auto-stop policy
        +  create      Create a new Sandbox environment
        +  default     Set the default Sandbox for SSH
        +  delete      Delete a Sandbox environment
        +  list        List your Sandbox environments
        +  register    Register this machine for sandbox SSH access
        +  ssh         SSH into a Sandbox environment
        +  ssh-key     Manage SSH keys registered with the sandbox service
        +  start       Start a stopped Sandbox environment
        +  status      Show Sandbox environment status
        +  stop        Stop a running Sandbox environment
        +
        +Flags:
        +  -h, --help   help for sandbox
        +
        +Global Flags:
        +      --debug            enable debug logging
        +  -o, --output type      output type: text or json (default text)
        +  -p, --profile string   ~/.databrickscfg profile
        +  -t, --target string    bundle target to use (if applicable)
        +
        +Use "databricks sandbox [command] --help" for more information about a command.
        +
        +Unexpected success
        +
        +Exit code: 1
        
FAIL

latest (v1.24.0):

acceptance_test.go:1345: Diff:
        --- cmd/sandbox/port-forward/invalid-forward/output.txt
        +++ /tmp/TestAcceptcmdsandboxport-forwardinvalid-forward3091525223/002/output.txt
        @@ -1,3 +1,108 @@
        -Error: invalid -L "8080": expected LOCAL:REMOTE ports, e.g. 8080:10080
        -Error: invalid -L "8080:8080": remote port must be between 10000 and 65535
        -Error: required flag(s) "forward" not set
        +Error: unknown shorthand flag: 'L' in -L
        +
        +Usage:
        +  databricks sandbox [command]
        +
        +Available Commands:
        +  config      Configure a Sandbox's name and auto-stop policy
        +  create      Create a new Sandbox environment
        +  default     Set the default Sandbox for SSH
        +  delete      Delete a Sandbox environment
        +  list        List your Sandbox environments
        +  register    Register this machine for sandbox SSH access
        +  ssh         SSH into a Sandbox environment
        +  ssh-key     Manage SSH keys registered with the sandbox service
        +  start       Start a stopped Sandbox environment
        +  status      Show Sandbox environment status
        +  stop        Stop a running Sandbox environment
        +
        +Flags:
        +  -h, --help   help for sandbox
        +
        +Global Flags:
        +      --debug            enable debug logging
        +  -o, --output type      output type: text or json (default text)
        +  -p, --profile string   ~/.databrickscfg profile
        +  -t, --target string    bundle target to use (if applicable)
        +
        +Use "databricks sandbox [command] --help" for more information about a command.
        +
        +Error: unknown shorthand flag: 'L' in -L
        +
        +Usage:
        +  databricks sandbox [command]
        +
        +Available Commands:
        +  config      Configure a Sandbox's name and auto-stop policy
        +  create      Create a new Sandbox environment
        +  default     Set the default Sandbox for SSH
        +  delete      Delete a Sandbox environment
        +  list        List your Sandbox environments
        +  register    Register this machine for sandbox SSH access
        +  ssh         SSH into a Sandbox environment
        +  ssh-key     Manage SSH keys registered with the sandbox service
        +  start       Start a stopped Sandbox environment
        +  status      Show Sandbox environment status
        +  stop        Stop a running Sandbox environment
        +
        +Flags:
        +  -h, --help   help for sandbox
        +
        +Global Flags:
        +      --debug            enable debug logging
        +  -o, --output type      output type: text or json (default text)
        +  -p, --profile string   ~/.databrickscfg profile
        +  -t, --target string    bundle target to use (if applicable)
        +
        +Use "databricks sandbox [command] --help" for more information about a command.
        +
        +Manage Databricks Sandbox environments.
        +
        +Sandbox provides SSH-accessible development environments backed by
        +microVM isolation. Each sandbox is a personal sandbox with pre-installed
        +tooling (Python, Node.js, Rust, Databricks CLI) and persistent storage.
        +
        +Getting started:
        +  databricks auth login --host https://...   # authenticate to a Databricks workspace
        +  databricks sandbox register                # generate and register an SSH key
        +  databricks sandbox create                  # provision a sandbox (becomes your default)
        +  databricks sandbox ssh                     # SSH to your default sandbox
        +
        +Common workflows:
        +  databricks sandbox ssh                     # SSH to your default sandbox
        +  databricks sandbox ssh my-project          # SSH to a named sandbox
        +  databricks sandbox list                    # list your sandboxes
        +  databricks sandbox create                  # create a new sandbox
        +  databricks sandbox delete my-project       # delete a sandbox
        +  databricks sandbox status my-project       # show sandbox status
        +
        +Usage:
        +  databricks sandbox [command]
        +
        +Available Commands:
        +  config      Configure a Sandbox's name and auto-stop policy
        +  create      Create a new Sandbox environment
        +  default     Set the default Sandbox for SSH
        +  delete      Delete a Sandbox environment
        +  list        List your Sandbox environments
        +  register    Register this machine for sandbox SSH access
        +  ssh         SSH into a Sandbox environment
        +  ssh-key     Manage SSH keys registered with the sandbox service
        +  start       Start a stopped Sandbox environment
        +  status      Show Sandbox environment status
        +  stop        Stop a running Sandbox environment
        +
        +Flags:
        +  -h, --help   help for sandbox
        +
        +Global Flags:
        +      --debug            enable debug logging
        +  -o, --output type      output type: text or json (default text)
        +  -p, --profile string   ~/.databrickscfg profile
        +  -t, --target string    bundle target to use (if applicable)
        +
        +Use "databricks sandbox [command] --help" for more information about a command.
        +
        +Unexpected success
        +
        +Exit code: 1

TestAccept/cmd/sandbox/port-forward/no-default: branch ✅ | main (21db1be) ❌ | latest (v1.24.0) ❌

main (21db1be):

acceptance_test.go:1345: Diff:
        --- cmd/sandbox/port-forward/no-default/output.txt
        +++ /tmp/TestAcceptcmdsandboxport-forwardno-default1527051527/002/output.txt
        @@ -1 +1,29 @@
        -Error: no default sandbox configured — run `databricks sandbox create` to provision one, or `databricks sandbox default <id>` to point at an existing sandbox
        +Error: unknown shorthand flag: 'L' in -L
        +
        +Usage:
        +  databricks sandbox [command]
        +
        +Available Commands:
        +  config      Configure a Sandbox's name and auto-stop policy
        +  create      Create a new Sandbox environment
        +  default     Set the default Sandbox for SSH
        +  delete      Delete a Sandbox environment
        +  list        List your Sandbox environments
        +  register    Register this machine for sandbox SSH access
        +  ssh         SSH into a Sandbox environment
        +  ssh-key     Manage SSH keys registered with the sandbox service
        +  start       Start a stopped Sandbox environment
        +  status      Show Sandbox environment status
        +  stop        Stop a running Sandbox environment
        +
        +Flags:
        +  -h, --help   help for sandbox
        +
        +Global Flags:
        +      --debug            enable debug logging
        +  -o, --output type      output type: text or json (default text)
        +  -p, --profile string   ~/.databrickscfg profile
        +  -t, --target string    bundle target to use (if applicable)
        +
        +Use "databricks sandbox [command] --help" for more information about a command.
        +

latest (v1.24.0):

acceptance_test.go:1345: Diff:
        --- cmd/sandbox/port-forward/no-default/output.txt
        +++ /tmp/TestAcceptcmdsandboxport-forwardno-default1210514569/002/output.txt
        @@ -1 +1,29 @@
        -Error: no default sandbox configured — run `databricks sandbox create` to provision one, or `databricks sandbox default <id>` to point at an existing sandbox
        +Error: unknown shorthand flag: 'L' in -L
        +
        +Usage:
        +  databricks sandbox [command]
        +
        +Available Commands:
        +  config      Configure a Sandbox's name and auto-stop policy
        +  create      Create a new Sandbox environment
        +  default     Set the default Sandbox for SSH
        +  delete      Delete a Sandbox environment
        +  list        List your Sandbox environments
        +  register    Register this machine for sandbox SSH access
        +  ssh         SSH into a Sandbox environment
        +  ssh-key     Manage SSH keys registered with the sandbox service
        +  start       Start a stopped Sandbox environment
        +  status      Show Sandbox environment status
        +  stop        Stop a running Sandbox environment
        +
        +Flags:
        +  -h, --help   help for sandbox
        +
        +Global Flags:
        +      --debug            enable debug logging
        +  -o, --output type      output type: text or json (default text)
        +  -p, --profile string   ~/.databrickscfg profile
        +  -t, --target string    bundle target to use (if applicable)
        +
        +Use "databricks sandbox [command] --help" for more information about a command.
        +
        
FAIL

TestAccept/cmd/sandbox/port-forward/not-found: branch ✅ | main (21db1be) ❌ | latest (v1.24.0) ❌

main (21db1be):

acceptance_test.go:1345: Diff:
        --- cmd/sandbox/port-forward/not-found/output.txt
        +++ /tmp/TestAcceptcmdsandboxport-forwardnot-found1829595542/002/output.txt
        @@ -1 +1,29 @@
        -Error: no sandbox named "no-such-box" — `databricks sandbox list` shows available IDs
        +Error: unknown shorthand flag: 'L' in -L
        +
        +Usage:
        +  databricks sandbox [command]
        +
        +Available Commands:
        +  config      Configure a Sandbox's name and auto-stop policy
        +  create      Create a new Sandbox environment
        +  default     Set the default Sandbox for SSH
        +  delete      Delete a Sandbox environment
        +  list        List your Sandbox environments
        +  register    Register this machine for sandbox SSH access
        +  ssh         SSH into a Sandbox environment
        +  ssh-key     Manage SSH keys registered with the sandbox service
        +  start       Start a stopped Sandbox environment
        +  status      Show Sandbox environment status
        +  stop        Stop a running Sandbox environment
        +
        +Flags:
        +  -h, --help   help for sandbox
        +
        +Global Flags:
        +      --debug            enable debug logging
        +  -o, --output type      output type: text or json (default text)
        +  -p, --profile string   ~/.databrickscfg profile
        +  -t, --target string    bundle target to use (if applicable)
        +
        +Use "databricks sandbox [command] --help" for more information about a command.
        +

latest (v1.24.0): same output as main (21db1be)

eng-dev-ecosystem-bot · 2026-11-07T07:15:01Z

✅ Integration test report

Commit: 1e44928

Run: 42349353890

	Env	✅pass	🙈skip	Time
✅	aws linux-2core-8gb	271	18	4:56
✅	aws-windows-latest-4core-16gb	273	16	3:06
✅	azure linux-2core-8gb	270	18	5:06
✅	azure-windows-latest-4core-16gb	272	16	3:05
✅	gcp linux-2core-8gb	271	18	4:59
✅	gcp-windows-latest-4core-16gb	273	16	3:09

Top 6 slowest tests (at least 2 minutes):

duration	env	testname
3:44	gcp linux-2core-8gb	TestAccept
3:30	azure linux-2core-8gb	TestAccept
3:12	aws linux-2core-8gb	TestAccept
3:04	gcp-windows-latest-4core-16gb	TestAccept
3:01	aws-windows-latest-4core-16gb	TestAccept
3:00	azure-windows-latest-4core-16gb	TestAccept

jaecho-db and others added 3 commits November 7, 2026 06:53

Add a changelog entry for databricks sandbox port-forward

1e44928

The sandbox command group is now visible as a Beta feature, so the new subcommand belongs in the release notes. Co-authored-by: Isaac <no-reply@databricks.com>

jaecho-db mentioned this pull request Nov 7, 2026

Add databricks sandbox port-forward #7367

Closed

jaecho-db marked this pull request as ready for review November 7, 2026 07:00

jaecho-db requested review from a team as code owners November 7, 2026 07:00

jaecho-db requested a review from rugpanov November 7, 2026 07:00

Navigation Menu

Repository navigation

Add `databricks sandbox port-forward` - #7395

Add `databricks sandbox port-forward`#7395
jaecho-db wants to merge 3 commits into
mainfrom
jaecho-db/sandbox-port-forward

jaecho-db commented Nov 7, 2026

Uh oh!

github-actions Bot commented Nov 7, 2026

Uh oh!

eng-dev-ecosystem-bot commented Nov 7, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

jaecho-db commented Nov 7, 2026

Changes

Why

Tests

Uh oh!

github-actions Bot commented Nov 7, 2026

Regression test report

Uh oh!

eng-dev-ecosystem-bot commented Nov 7, 2026

✅ Integration test report

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants