Skip to content
DashboardGet API key

Ports, SSH and the desktop

Reach a service on a zavu.run URL, connect over SSH, or open the machine screen in your browser

View .md

Ports

Start a server inside the sandbox, listening on 0.0.0.0, then give its port a URL:

await zavu.sandboxes.commands.run(sandboxId, {
  command: "python3 -m http.server 3000",
  background: true,
});

const { port } = await zavu.sandboxes.ports.expose(sandboxId, { port: 3000 });
console.log(port.url); // https://k3x7…q2.zavu.run/?_token=…

The URL is on zavu.run. HTTP and WebSockets both go through, so a dev server with hot reload works.

  • Private (default). The URL carries an access token in its query string: anyone holding the full URL can open it, so treat it as a secret. In a browser the token moves into a cookie for that host on the first visit and leaves the address bar, so the page's own links, assets and WebSockets work. Other clients send ?_token= on every request.
  • Public. Pass public: true for a URL anyone can open. Calling again with the other value switches the same URL.

Asking again for the same port returns the same URL. It survives a stop and resume: while the sandbox is stopped it answers 503, and once the sandbox is deleted it answers 404. A sandbox exposes at most 20 ports, and zavu.sandboxes.ports.list(sandboxId) lists them.

SSH

Authorize your public key on the running machine. The answer carries the command to connect; you log in as its user, which has passwordless sudo.

const { ssh } = await zavu.sandboxes.ssh.authorize(sandboxId, {
  publicKey: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGq user@laptop",
});
console.log(ssh.command); // ssh user@203.0.113.10

Send the one line in your .pub file. A private key is refused with 400. The address changes after a stop and resume: authorize the key again then. This also works from an editor that opens remote folders over SSH.

The desktop

Every sandbox has a graphical desktop with Chrome. Open it to watch an agent drive the browser, or to use the machine yourself.

const { desktop } = await zavu.sandboxes.desktop.open(sandboxId, { view: "browser" });
console.log(desktop.url);

view is desktop for the whole screen (the default) or browser for Chrome alone. The answer is a short-lived URL on zavu.run that streams the screen, mouse and keyboard included:

  • Open it within a few minutes. Anyone holding it can use the machine until the sandbox stops, so treat it as a secret.
  • The first request after a start can answer 409 sandbox_not_ready for a few seconds while the stream is prepared. Retry.
  • Ask for a new one after a resume.