Boat sandbox · searchSDK Docs

Before you start

Boat provides Ubuntu sandboxes with SSH and Node. This guide runs searchSDK inside a sandbox you create and control. The downloadable runner uses deterministic fixtures by default. It does not create or manage a sandbox.

You need your own Boat account and an installed, signed-in Boat CLI. Follow Boat's official quickstart, review its installer before executing it, and check its current billing terms before creating a sandbox.
Install @belweave/search-sdk@alpha in the sandbox application. Alpha APIs may change; retain package-lock.json to reproduce the resolved version.
Use Node 24.22.1 or a newer patched Node 24 release. The fixture needs no search-provider key. Optional live search needs your own Context.dev key and can incur provider charges.

1. Open your sandbox

On your own computer, after completing Boat's official CLI setup, create a sandbox with a 30-minute auto-stop deadline. --no-env prevents Boat from injecting your account's configured secrets, repositories, and agent logins. Keep the printed sandbox ID; replace YOUR_SANDBOX_ID below with that actual ID.

Your computer · Boat CLI

boat status --check
boat new --type small --ttl 1800 --no-env

# Use the ID printed by boat new:
boat info YOUR_SANDBOX_ID
boat ssh YOUR_SANDBOX_ID

The remaining setup and search commands run inside that SSH shell. SSH work does not extend the auto-stop deadline. Install and run one recipe at a time; leave enough time to clean up before the deadline.

2. Check Node inside the sandbox

Inside the sandbox · check Node

node --version
npm --version

Use Node 24.22.1 or a newer patched Node 24 release before continuing. If you already use nvm, run nvm install 24.22.1 and nvm use 24.22.1. Otherwise, follow Node's official installation instructions for your sandbox architecture.

Official Node downloads

3. Install searchSDK

Create a server application inside the sandbox and install the alpha channel. The package is ESM with declarations and zero runtime dependencies. Keep the generated lockfile if you retain the project.

Inside the sandbox · Bash

mkdir searchsdk-boat
cd searchsdk-boat
npm init --yes
npm install @belweave/search-sdk@alpha

Installation and optional source build

4. Inspect and run the recipe

In searchsdk-boat, download the plain ESM file from this documentation site, inspect it, then execute it. It requires no extra runtime dependencies beyond the SDK package. You can also save the linked file locally and copy it with Boat's documented boat scp command.

Inside the sandbox · download for review

curl --fail --location --show-error https://searchsdk.dev/recipes/boat/search.mjs -o search.mjs
cat search.mjs

Inside the sandbox · run after review

node search.mjs

Expect JSON with mode: "fixture", a mock provider, three fixed example-domain results, and source provenance. No search-provider request is sent. Attempt timestamps and durations vary; the fixture is not evidence of live retrieval quality or Boat performance.

The runner uses the same SDK calls as this complete fixture example. It caps results at three, sets a ten-second total deadline and an eight-second attempt deadline, disables retries, and passes a cancellation signal when interrupted.

boat-fixture.ts · fixture

import { createSearch } from '@belweave/search-sdk';
import { createMockProvider } from '@belweave/search-sdk/testing';

const client = createSearch({
  provider: createMockProvider(),
  timeoutMs: 10_000,
  attemptTimeoutMs: 8_000,
  retry: { maxRetries: 0 },
});
const response = await client.web.search({ query: 'SQLite write concurrency', limit: 3 });
console.log(response.provider, response.results, response.attempts);

5. Optional: one live search

Only continue if you intend to make a potentially billable Context.dev request. Enter your provider key in the interactive SSH session using this Bash prompt. The key is hidden while typing, stays in the subshell's environment and runner memory, and is removed when they exit. The runner requires --live; setting a key alone never enables live search.

Inside the sandbox · Bash · live opt-in

(
  set +x
  ulimit -c 0
  read -r -s -p 'Context.dev API key (hidden): ' CONTEXT_API_KEY
  printf '\n'
  export CONTEXT_API_KEY
  node search.mjs --live
)

The runner makes one normalized search with no configured fallback or retries. Context.dev can request at least ten native results before the SDK trims the output to three, which can affect credits. Cancellation and deadlines limit local waiting; they cannot guarantee a remote request was not processed or billed.

6. Finish and clean up

Exit SSH and manage the sandbox from your own computer. Choose deletion when you are finished with the disposable environment; the CLI asks for confirmation. Export only non-secret artifacts you need first.

Your computer · delete the disposable sandbox

# Leave the sandbox SSH shell:
exit

# On your computer, use your recorded ID:
boat delete YOUR_SANDBOX_ID

If you deliberately want to keep the disk instead, run boat stop YOUR_SANDBOX_ID and check boat info YOUR_SANDBOX_ID until it is stopped. Stopping ends running processes and snapshots disk; it does not erase files or earlier snapshots. Auto-stop has the same persistence caveat. Review Boat's current retention policy before relying on stopped storage.

Automating the lifecycle later

Boat's @boatdev/sdk and HTTP API are separate infrastructure clients. searchSDK is the search client running inside the sandbox. For automation, use Boat's official TypeScript guide: keep BOAT_API_KEY on the trusted controller, wait for readiness, bound the sandbox lifetime, inspect command exit status, and clean up in finally. Its synchronous command API has a separate timeout; keep installation and execution within that timeout or use the documented streaming helper.

Provisioning and live provider execution are intentionally manual in this recipe. No Boat API key is required inside the sandbox. Benchmarks are separate work and are not run by these commands.