Skip to content

Serve a web app

A preview gives one port of a sandbox an HTTPS address. Use it to show an agent's work, run a dev server, or test a web app before you deploy it.

Updated .md

Start a server and share its port#

Start the server with POST /v2/sandboxes/{id}:exec and wait false, so it keeps running after the call returns. Then share its port with POST /v2/sandboxes/{id}/previews.

TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime();const sandbox = await runtime.sandboxes.create();try {  const app = `require("http").createServer((req, res) => res.end("hello from " + req.url)).listen(3000);`;  await sandbox.files.write("/workspace/server.js", app);  await sandbox.exec(["node", "/workspace/server.js"], { wait: false });  const preview = (await runtime.previews.create(sandbox.id, { port: 3000 })).info;  // A private preview needs its token, in a header (or `?runtime_preview_token=` for a browser).  const open = () => fetch(preview.url, { headers: { "x-runtime-preview-token": preview.token! } });  let page = await open();  for (let i = 0; i < 20 && page.status !== 200; i++) {    await new Promise((r) => setTimeout(r, 250)); // the server may still be starting    page = await open();  }  console.log(page.status, await page.text());  if (page.status !== 200) throw new Error(`preview answered ${page.status}`);} finally {  await sandbox.delete();}

Private and public previews#

  • visibility: private (default): a token is needed. public: anyone with the address.
  • token: A token signed for this answer, for a private preview and a key that may create one: send it in the x-runtime-preview-token header, or open the url with ?runtime_preview_token=<token> in a browser. tokenExpiresAt says when it stops working.
  • ttlSeconds: The token's lifetime in seconds, from 60 until the calling key's own end (a year at most); a day when omitted, or the key's end when that is sooner.
  • embedOrigins: The sites that may show it in an iframe; omitted on one that exists, kept as it is; empty for any site.
  • POST /v2/previews/{name}:rotate refuses every token issued so far. POST /v2/previews/{name}:sign issues a new one.
  • DELETE /v2/previews/{name} stops sharing the port.

A preview's address answers once its state is ready. Deleting the sandbox removes its previews.

Next steps#

Give this to your agent#

Paste this into your coding agent:

Read https://withruntime.com/docs/web-app.md. Run this project's web server in a Runtime sandbox, share its port with a private preview, and print the preview's url with its token (?runtime_preview_token=) so I can open it. Delete the preview and the sandbox when I say I'm done.

This page as Markdown: https://withruntime.com/docs/web-app.md

Try it on your own work.Signing up takes no card. Your first sandbox asks for one, and the trial starts then. Or paste the setup prompt into your agent.
Start your free trial