Networking and tunnels

Open sandbox applications in your browser and forward services to your computer.

Your application runs inside the sandbox. Use the Adria CLI on your local computer to connect its port to local loopback over SSH.

Start a development server

Local: open a persistent terminal for the server:

cube connect feature/payments --tmux web

Sandbox: run your project's development command. For a Bun project with a dev script configured for port 3000:

bun install
bun run dev

Use the port your server actually prints. Detach with Ctrl+B, then D to keep it running while you open the preview locally.

Open a preview

Local:

cube open 3000 --session feature/payments

Adria forwards sandbox port 3000 and opens the local address in your browser. Keep the command running while using the application. Ctrl+C closes the tunnel; it leaves the remote server running.

The tunnel reaches the sandbox's localhost, so a server listening on remote loopback works. If it runs in Docker, publish the container port to the VM first.

Forward any TCP service

# Local: connect a database client to localhost:5432.
cube forward 5432 --session feature/payments

# Or map remote port 3000 to local port 8080.
cube forward 3000:8080 --session feature/payments

The syntax is remote-port:local-port. Run each tunnel in a separate terminal. If the requested local port is occupied, Adria can select an available one; use the address printed by the command.

Both open and forward bind to 127.0.0.1 on your computer. They do not create a public preview URL. Other people need their own authorized access.

Select the right sandbox

Use --session <branch-or-id> when working with several sandboxes. Without that flag, Adria uses CUBE_SESSION_ID if set, then your local Git branch.

Port commands require a ready Session. They do not start or resume compute. If the Session is paused, run cube connect <session>, restart the service, then open the tunnel from a local terminal.

Troubleshooting

Symptom	What to check
The Session is not ready	Connect or start it first and wait for readiness.
The browser cannot reach the app	Confirm the process is running and use its actual listening port.
A container app is unreachable	Publish its container port on the sandbox VM.
The local port differs from the example	Use Adria's printed address or choose another local port with `forward`.
A preview stops after closing the terminal	Keep the forwarding command running for the lifetime of the preview.

To open Chromium inside a sandbox instead, see Computer use.