# Connect to Beav on the user's computer

Beav is a local-first creator asset workspace. This public guide only helps you find the user's local Beav instance. The local discovery file, manifest, and guide are the source of truth for the installed version's capabilities.

## Completion contract

When the user asks you to connect to Beav, do not stop after reading this page or describing commands. Complete the host check, discover the local gateway, read the local manifest and guide, create a Beav ACP session, start the requested creator task, and report the resulting session and run state.

You are complete only when one of these is true:

1. A Beav ACP session exists, the first run has been submitted, and you report its session ID and current status.
2. A concrete blocking condition prevents local access, and you report the exact failed step and the user action required to continue.

## 1. Host environment gate

First determine whether you are running in a desktop agent on the same computer as Beav.

- If you are in a web chat, remote container, hosted sandbox, or another computer, stop before attempting localhost calls. Tell the user to open their desktop agent on the computer where Beav is installed and paste their original request there.
- If you are on the user's computer, continue.
- If you cannot determine the environment, ask only whether this conversation is running locally on the computer with Beav.

Do not expose the Beav gateway to the public internet to work around a remote environment.

## 2. Confirm Beav is running

Beav Desktop must be open and its ACP Gateway must be enabled under the remote API settings. Keep Local only enabled unless the user is deliberately testing a trusted local network configuration.

Do not invent a debug endpoint. Use the existing ACP discovery, manifest, guide, session, run, event, and artifact routes.

## 3. Discover the local endpoint

Use this order:

1. Read the file path in the `REDBOX_ACP_DISCOVERY_FILE` environment variable, if present.
2. Otherwise try the platform compatibility path:
   - macOS: `~/Library/Application Support/RedBox/acp-gateway.json`
   - Windows: `%APPDATA%\RedBox\acp-gateway.json`
   - Linux: `$XDG_CONFIG_HOME/RedBox/acp-gateway.json` or `~/.config/RedBox/acp-gateway.json`
3. If the file is absent, try the compatibility endpoint `http://127.0.0.1:31937/acp/v1`.

The compatibility names `RedBox`, `REDBOX_ACP_*`, and `redbox-agent.json` are intentional parts of the current Beav protocol. Do not substitute unimplemented `BEAV_*` names.

From the discovery JSON, read at least:

- `endpointUrl`
- `manifestUrl`
- `guideUrl`
- `enabled`
- `listening`
- `authRequired`

Prefer discovered URLs over a hard-coded port.

## 4. Read the local contract

Fetch `manifestUrl` and `guideUrl` completely before creating a task.

- The manifest is the machine-readable capability contract.
- The guide is the installed Beav version's conversation procedure.
- Do not promise image, video, audio, browser, publishing, or export capabilities unless the local manifest exposes them.

## 5. Authenticate safely

If `authRequired` is true, read the token from `REDBOX_ACP_TOKEN` and send it only as:

`Authorization: Bearer <token>`

Never put the token in a prompt, URL, query parameter, cookie, source file, screenshot, documentation, or log. If no token is available, tell the user to create an ACP client token in Beav settings and provide it to the desktop agent through a secure environment variable.

## 6. Create a Beav creator session

Use the discovered endpoint and the local guide. Unless the user explicitly asked to continue an existing ACP session, create a new session with a clear title and objective.

Example request body:

```json
{
  "client": { "name": "Codex", "kind": "coding_agent" },
  "title": "Creator task",
  "objective": "Use Beav materials to complete the user's requested content task"
}
```

Send it to `POST endpointUrl + /sessions`. Preserve the returned `sessionId` or `acpSessionId`.

For a different host, set `client.name` and `client.kind` to truthful values. Do not impersonate another agent.

## 7. Start the user's task

Submit the user's actual creator request to `POST endpointUrl + /runs` using the created session ID. Include the requested platform, audience, constraints, relevant Beav material references, and desired output when known. Do not add paid generation or external publication unless the user requested it.

Example request body:

```json
{
  "client": { "name": "Codex", "kind": "coding_agent" },
  "sessionId": "acp-session-...",
  "prompt": "Read the current workspace context, tell the user what materials and creator capabilities are available, then ask what they want to make."
}
```

## 8. Poll events and handle approval

Read the run and its events using the URLs returned by Beav or the local guide. Use cursor and limit when polling. Do not restart the same task just because it takes time.

Expected states include:

- `queued`
- `running`
- `awaiting_approval`
- `completed`
- `failed`
- `cancelled`
- `expired`

If a run is `awaiting_approval`, tell the user what capability is waiting and let them approve or reject it in Beav. Never bypass approval by changing routes, disabling policy, or resubmitting the same operation.

Paid generation, browser control, deletion, publishing, and external export are approval-sensitive operations.

## 9. Preserve artifacts and conversation state

Keep the returned session ID for follow-up turns. Read artifact references through the local artifact route and leave large files in Beav. Do not inline large images, audio, video, project packages, or internal store snapshots into chat.

Continuing the same creator objective must reuse the existing ACP session instead of creating a new session for every message.

## 10. Required self-report

After the first run is submitted, report:

- Beav connection: connected or blocked
- Local manifest and guide: read or failed
- Session ID
- Run ID and current status
- Whether approval is required
- The next question or action for the user

Do not claim the creator task is finished merely because the request was accepted. A finished task requires a completed run and readable required artifacts.

## Human documentation

- Beav Agent guide: https://redbox.ziz.hk/docs/agent
- Connection steps: https://redbox.ziz.hk/docs/agent/connect
- Capabilities and approvals: https://redbox.ziz.hk/docs/agent/capabilities-and-approvals
- Browser extension install: https://redbox.ziz.hk/docs/browser-extension/install