Checkout the full documentation here
Hyperbrowser can be installed via npm by running:
npm install @hyperbrowser/sdkor
yarn add @hyperbrowser/sdkimport{chromium}from"playwright-core";import{Hyperbrowser}from"@hyperbrowser/sdk";import{config}from"dotenv";config();constclient=newHyperbrowser({apiKey: process.env.HYPERBROWSER_API_KEY,});constmain=async()=>{constsession=awaitclient.sessions.create();try{constbrowser=awaitchromium.connectOverCDP(session.wsEndpoint);constdefaultContext=browser.contexts()[0];constpage=awaitdefaultContext.newPage();// Navigate to a websiteconsole.log("Navigating to Hacker News...");awaitpage.goto("https://news.ycombinator.com/");constpageTitle=awaitpage.title();console.log("Page 1:",pageTitle);awaitpage.evaluate(()=>{console.log("Page 1:",document.title);});awaitpage.goto("https://example.com");console.log("Page 2:",awaitpage.title());awaitpage.evaluate(()=>{console.log("Page 2:",document.title);});awaitpage.goto("https://apple.com");console.log("Page 3:",awaitpage.title());awaitpage.evaluate(()=>{console.log("Page 3:",document.title);});awaitpage.goto("https://google.com");console.log("Page 4:",awaitpage.title());awaitpage.evaluate(()=>{console.log("Page 4:",document.title);});}catch(err){console.error(`Encountered error: ${err}`);}finally{awaitclient.sessions.stop(session.id);}};main();import{connect}from"puppeteer-core";import{Hyperbrowser}from"@hyperbrowser/sdk";import{config}from"dotenv";config();constclient=newHyperbrowser({apiKey: process.env.HYPERBROWSER_API_KEY,});constmain=async()=>{constsession=awaitclient.sessions.create();try{constbrowser=awaitconnect({browserWSEndpoint: session.wsEndpoint,defaultViewport: null,});const[page]=awaitbrowser.pages();// Navigate to a websiteconsole.log("Navigating to Hacker News...");awaitpage.goto("https://news.ycombinator.com/");constpageTitle=awaitpage.title();console.log("Page 1:",pageTitle);awaitpage.evaluate(()=>{console.log("Page 1:",document.title);});awaitpage.goto("https://example.com");console.log("Page 2:",awaitpage.title());awaitpage.evaluate(()=>{console.log("Page 2:",document.title);});awaitpage.goto("https://apple.com");console.log("Page 3:",awaitpage.title());awaitpage.evaluate(()=>{console.log("Page 3:",document.title);});awaitpage.goto("https://google.com");console.log("Page 4:",awaitpage.title());awaitpage.evaluate(()=>{console.log("Page 4:",document.title);});}catch(err){console.error(`Encountered error: ${err}`);}finally{awaitclient.sessions.stop(session.id);}};main();For local sandbox development, you can explicitly route sandbox runtime traffic through a regional proxy override:
constclient=newHyperbrowser({apiKey: process.env.HYPERBROWSER_API_KEY,runtimeProxyOverride: process.env.REGIONAL_PROXY_DEV_HOST,});import{Hyperbrowser}from"@hyperbrowser/sdk";constclient=newHyperbrowser({apiKey: process.env.HYPERBROWSER_API_KEY,});constmain=async()=>{constsandbox=awaitclient.sandboxes.create({imageName: "ubuntu-24-node",region: "us-west",cpu: 4,memoryMiB: 4096,diskMiB: 8192,});// Provide exactly one launch source:// snapshotName or imageName.// snapshotId requires snapshotName and imageId requires imageName.// cpu, memoryMiB, and diskMiB are only available for image launches.constversion=awaitsandbox.exec("node -v");console.log(version.stdout.trim());awaitsandbox.files.writeText("/tmp/hello.txt","hello from sdk");constcontent=awaitsandbox.files.readText("/tmp/hello.txt");console.log(content);constwatch=awaitsandbox.files.watchDir("/tmp",(event)=>{if(event.type==="write"){console.log(event.name);}},{recursive: false,});awaitsandbox.files.writeText("/tmp/watch-demo.txt","watch me");awaitwatch.stop();constproc=awaitsandbox.processes.start("echo process-started && sleep 1 && echo process-finished",{runAs: "root",}});forawait(consteventofproc.stream()){if(event.type==="stdout"){process.stdout.write(event.data);}}constterminal=awaitsandbox.terminal.create({command: "bash",cols: 120,rows: 30,});constconnection=awaitterminal.attach();awaitconnection.write("echo terminal-ok\n");forawait(consteventofconnection.events()){if(event.type==="output"&&event.data.includes("terminal-ok")){break;}}awaitconnection.close();constsnapshot=awaitsandbox.createMemorySnapshot();console.log(snapshot.snapshotId);awaitsandbox.stop();};main().catch(console.error);Reconnect an existing sandbox:
constsandbox=awaitclient.sandboxes.connect("sandbox-id");awaitsandbox.files.readText("/tmp/hello.txt");awaitsandbox.stop();connect() refreshes runtime auth and throws if the sandbox is no longer running.
Create a sandbox with pre-exposed ports:
constsandbox=awaitclient.sandboxes.create({imageName: "node",cpu: 2,memoryMiB: 2048,diskMiB: 8192,exposedPorts: [{port: 3000,auth: true}],});console.log(sandbox.exposedPorts[0].browserUrl);Manage volumes and mount them into a sandbox:
constvolume=awaitclient.volumes.create({name: "project-cache"});constvolumes=awaitclient.volumes.list();constsameVolume=awaitclient.volumes.get(volume.id);constsandbox=awaitclient.sandboxes.create({imageName: "node",mounts: {"/workspace/cache": {id: sameVolume.id,type: "rw",shared: true,},},});awaitsandbox.stop();awaitclient.volumes.delete(sameVolume.id);List sandboxes with time-range and search filters:
constsandboxes=awaitclient.sandboxes.list({status: "active",start: Date.now()-60*60*1000,end: Date.now(),search: "sbx_",limit: 25,});List snapshots for a specific image:
constsnapshots=awaitclient.sandboxes.listSnapshots({imageName: "node",status: "created",limit: 10,});Expose and unexpose ports:
constsandbox=awaitclient.sandboxes.create({imageName: "node"});constexposure=awaitsandbox.expose({port: 8080,auth: true});console.log(exposure.url,exposure.browserUrl,exposure.browserUrlExpiresAt);awaitsandbox.unexpose(8080);Write batch files with per-entry options:
awaitsandbox.files.write([{path: "/tmp/hello.txt",data: "hello",append: true,mode: "600",},{path: "/tmp/payload.bin",data: Buffer.from([1,2,3]).toString("base64"),encoding: "base64",},]);Resume a PTY attach from a cursor:
constterminal=awaitsandbox.terminal.create({command: "bash",rows: 24,cols: 80,});constconnection=awaitterminal.attach(10);