> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trynia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox search

> Run a read-only agent against a cloned Git repository in an ephemeral sandbox — no indexing required

## Overview

Sandbox search provisions an isolated runtime, clones a **public** Git repository (GitHub, GitLab, or Bitbucket), and runs a **read-only** agent that answers your question using **local files only** (no web fetch, no repository edits). When the job finishes, the sandbox is destroyed.

Use sandbox search when you want a deep, file-grounded answer against a specific ref **without** adding the repo as an indexed [source](/source-types). For multi-source or already-indexed content, prefer [`POST /search`](/api-guide#quick-start-examples) instead.

<Warning>
  **`repository` can be either a full HTTPS repository URL or `owner/repo`
  shorthand**. If you use shorthand, the optional `provider` field defaults to
  `github`.
</Warning>

## When to use what

| Approach                                                                        | Best for                                                                                                                                  |
| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Sandbox search** — API (`POST /sandbox/search`) or CLI (`nia search sandbox`) | One-off questions against a public repo URL or `owner/repo` shorthand; full tree available in the VM; GitLab/Bitbucket as well as GitHub. |
| **Unified search** (`POST /search` / `nia search query`)                        | Indexed sources, multiple repositories, documentation, and hybrid retrieval you already use in Nia.                                       |
| **Tracer** ([Tracer](/tracer))                                                  | GitHub-centric agent that uses GitHub APIs (no full clone in your account flow).                                                          |

## Authentication

Same as the rest of the API: `Authorization: Bearer YOUR_API_KEY`. See the [API Guide](/api-guide).

## Endpoints

| Method | Path                    | Purpose                                                                                  |
| ------ | ----------------------- | ---------------------------------------------------------------------------------------- |
| `POST` | `/sandbox/search`       | Start a search job; returns JSON or Server-Sent Events (SSE).                            |
| `GET`  | `/sandbox/jobs/{jobId}` | Fetch the same job record (status, result, errors). Only the owning user can read a job. |

Base URL: `https://apigcp.trynia.ai/v2` (see [API Guide](/api-guide#base-url)).

## Request body (`POST /sandbox/search`)

| Field        | Type    | Required | Description                                                                                                                                 |
| ------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `repository` | string  | Yes      | Full HTTPS URL to a public GitHub, GitLab, or Bitbucket repository, or `owner/repo` shorthand.                                              |
| `query`      | string  | Yes      | Natural-language question for the agent.                                                                                                    |
| `ref`        | string  | No       | Branch, tag, or commit to check out.                                                                                                        |
| `provider`   | string  | No       | Repository provider for shorthand input: `github`, `gitlab`, or `bitbucket`. Defaults to `github`. Ignored when `repository` is a full URL. |
| `stream`     | boolean | No       | See [Streaming](#streaming) below.                                                                                                          |

## JSON response

By default the handler returns **JSON** when the client does not ask for SSE and `stream` is not `true`. The payload describes the job, sandbox lifecycle, optional git cache metadata, and (when complete) the execution result:

* **`workspaceKind`** — e.g. git repository workspace.
* **`job`** — `id`, `status`, `query`, `createdAt`, optional `startedAt` / `completedAt`.
* **`sandbox`** — Sandbox identifiers, runtime status, workspace path, preparation and deletion timestamps when applicable.
* **`repository`** — Present for git workspaces when cache metadata exists (canonical URL, ref, commit SHA, volume hints, etc.).
* **`result`** — When the job completed successfully: `answer`, `rawOutput`, `command`, `exitCode`, `workspacePath`, `volumeName`, `cacheSubpath`.
* **`error`** — When the job failed: `message`, optional `name`, `code`, `stack`, `details`, etc.

Statuses evolve from provisioning through running to `completed`, `failed`, or `cancelled`. Poll `GET /sandbox/jobs/{jobId}` with the `job.id` from the response if you need updates from another process.

## Streaming

The API returns **Server-Sent Events** when either:

* the client sends `Accept: text/event-stream`, **or**
* the JSON body includes `"stream": true`.

Send **`"stream": false"`** to force a **JSON** response even if `Accept` prefers SSE.

SSE payloads are JSON objects per event, one per `data:` line. Event `type` values include:

| `type`     | Meaning                                                                                        |
| ---------- | ---------------------------------------------------------------------------------------------- |
| `job`      | Includes `jobId` for correlation and polling.                                                  |
| `status`   | Job and runtime status, optional sandbox id/state.                                             |
| `opencode` | Read-only agent stdout/stderr lines or structured stream payloads (`stream`, `line`, `event`). |
| `result`   | Final job payload (`jobId` + serialized job).                                                  |
| `error`    | Error message (and optional `name` / `code`).                                                  |
| `done`     | Stream complete.                                                                               |

The server may emit `: keep-alive` comment lines every few seconds to keep connections open.

Closing the HTTP client **cancels** the in-flight request; the pipeline treats that as cancellation where supported.

## Examples

### Search (JSON)

```bash theme={null}
curl -sS -X POST https://apigcp.trynia.ai/v2/sandbox/search \
  -H "Authorization: Bearer $NIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "vercel/ai",
    "ref": "main",
    "query": "Where is streamText implemented and how does it relate to the data stream protocol?"
  }'
```

### Search (SSE)

```bash theme={null}
curl -N -X POST https://apigcp.trynia.ai/v2/sandbox/search \
  -H "Authorization: Bearer $NIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "repository": "gitlabhq/gitlabhq",
    "provider": "gitlab",
    "query": "Summarize the core packages in this monorepo."
  }'
```

Or keep default `Accept` and set `"stream": true` in the body. If you send a full URL and `provider`, the URL takes precedence.

### Poll job by id

```bash theme={null}
curl -sS "https://apigcp.trynia.ai/v2/sandbox/jobs/$JOB_ID" \
  -H "Authorization: Bearer $NIA_API_KEY"
```

## CLI usage

The [Nia CLI](/integrations/installation/cli) exposes sandbox search as `nia search sandbox`. It streams progress by default and formats output for interactive terminals.

### Flags

| Flag                       | Short | Type    | Default | Description                                                            |
| -------------------------- | ----- | ------- | ------- | ---------------------------------------------------------------------- |
| `--repository`             | `-r`  | string  | —       | Full HTTPS URL of the git repository (required).                       |
| `--ref`                    | —     | string  | —       | Branch, tag, or commit to check out.                                   |
| `--stream` / `--no-stream` | —     | boolean | `true`  | Stream progress updates. Use `--no-stream` for a single JSON response. |
| `--api-key`                | —     | string  | —       | Override the API key for this invocation.                              |
| `--verbose`                | —     | —       | —       | Show full job metadata and agent protocol events.                      |

### Examples

Search a repository (streams by default):

```bash theme={null}
nia search sandbox "Where is streamText implemented?" \
  -r vercel/ai
```

Search a specific ref:

```bash theme={null}
nia search sandbox "Explain the plugin system" \
  -r vitejs/vite --ref main
```

Disable streaming for a single JSON response:

```bash theme={null}
nia search sandbox "How does the router work?" \
  -r honojs/hono --no-stream
```

Re-fetch a previous job:

```bash theme={null}
nia search sandbox job <job-id>
```

Pipe structured output to `jq`:

```bash theme={null}
nia search sandbox "List all exported functions" \
  -r sindresorhus/ky | jq .result.answer
```

<Tip>
  On interactive terminals the CLI prints a clean text answer. When piped or
  redirected, it emits structured JSON — useful for composing with other tools.
</Tip>

## Errors

Common API error codes for this module:

| Code                          | Typical cause                                                                                   |
| ----------------------------- | ----------------------------------------------------------------------------------------------- |
| `INVALID_SANDBOX_REPOSITORY`  | Repository missing, invalid, shorthand malformed, or full URL host not GitHub/GitLab/Bitbucket. |
| `SANDBOX_PROVISIONING_FAILED` | Sandbox or workspace setup failed.                                                              |
| `SANDBOX_COMMAND_FAILED`      | Agent command exited with failure.                                                              |
| `SANDBOX_QUERY_JOB_NOT_FOUND` | Unknown `jobId` or job owned by another user.                                                   |

See [API Guide — Error handling](/api-guide#error-handling) for HTTP status conventions.

## API reference

Full request/response schemas for these routes live in the [API Reference](/api-reference) under the **Sandbox** tag.