# Run searchSDK in Boat

Install the alpha package in your own Boat sandbox, run a fixture, then optionally make one server-side search with your own key.

Canonical: https://searchsdk.dev/docs/guides/boat
Markdown: https://searchsdk.dev/docs/guides/boat.md

<a id="before-you-start"></a>

## 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.

> **Verification boundary**
> The SDK contract and fixture runner are checked locally. A live Boat session and live provider search have not been verified. This is a setup recipe, not a benchmark or a partnership claim.

- [Boat quickstart](https://docs.boat.dev/quickstart)
- [Boat pricing](https://docs.boat.dev/pricing)
- [Optional source build](https://searchsdk.dev/docs/installation#pack-locally)
- [Download search.mjs](https://searchsdk.dev/recipes/boat/search.mjs): Save the file in your sandbox application and inspect it before running. Fixture mode is the default.

<a id="open-a-sandbox"></a>

## 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**

```bash
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.

- [Boat SSH access](https://docs.boat.dev/ssh-access)
- [Boat credential inheritance](https://docs.boat.dev/environments/access)

<a id="prepare-node"></a>

## 2. Check Node inside the sandbox

**Inside the sandbox · check Node**

```bash
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](https://nodejs.org/en/download)

<a id="build-the-alpha"></a>

## 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**

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

- [Installation and optional source build](https://searchsdk.dev/docs/installation)

<a id="run-the-fixture"></a>

## 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**

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

**Inside the sandbox · run after review**

```bash
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**

```typescript
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);
```

<a id="optional-live-search"></a>

## 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**

```bash
(
  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.

> **Keep credentials out of disk and logs**
> Do not put provider or Boat account keys in source, `.env`, shell startup files, command arguments, public client code, or snapshots. Do not pass a provider key through a Boat exec command: command history can retain command text. This recipe writes no credential file, but other processes in the same sandbox may access process memory or environment. Use a sandbox you control and trust.

- [Context.dev adapter and billing boundary](https://searchsdk.dev/docs/providers/context)
- [SDK cancellation and deadlines](https://searchsdk.dev/docs/reliability/timeouts)

<a id="finish-and-clean-up"></a>

## 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**

```bash
# 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.

> **Snapshots are persistent data**
> Deleting the sandbox starts irreversible background deletion. Follow the deletion operation to completion. Named snapshots, forks, and other shared artifacts can retain data independently and need separate cleanup. If a key was written to disk or logged accidentally, revoke it; deleting a current file or merely stopping the sandbox does not erase older copies.

- [What Boat snapshots save](https://docs.boat.dev/snapshots/whats-saved)
- [Boat stop and deletion commands](https://docs.boat.dev/cli-reference#boat-delete-id)
- [Boat deletion API semantics](https://docs.boat.dev/api/reference/sandboxes/permanently-delete-sandbox-data)

<a id="programmatic-lifecycle"></a>

## 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.

- [Boat TypeScript SDK](https://docs.boat.dev/sdks/typescript)
- [Boat HTTP API](https://docs.boat.dev/api/v1)
- [Boat documentation index](https://docs.boat.dev/llms.txt)
- [Test integrations with fixtures](https://searchsdk.dev/docs/guides/testing)