Buildify OpenCode Agent

buildify-opencode-agent connects Buildify Agent Broker to the local OpenCode CLI. It pulls opencode.task jobs from Broker, runs them through opencode acp, then reports task results, token usage, cost, and errors back to Broker.

Requirements

• Node.js 18 or newer
• OpenCode CLI installed and available on the agent machine
• Network access from the agent machine to Buildify Agent Broker
• Provider API credentials for the models you want to use

Check OpenCode:

opencode --version
opencode models

Install

From npm:

npm install -g @buildify-cli/opencode-agent

From this repository:

cd buildify-opencode-agent
npm install
npm run build
npm link

Verify:

buildify-opencode-agent --version
buildify-opencode-agent --help

Quick Start

Create the default config file:

buildify-opencode-agent config init

Set Broker connection values:

buildify-opencode-agent config set \
  server=http://localhost:8080 \
  token=<broker-token> \
  clientId=<agent-client-id>

Start in the foreground:

buildify-opencode-agent start --logs

Start as a background daemon:

buildify-opencode-agent start --daemon
buildify-opencode-agent status
buildify-opencode-agent stop

Install as a macOS launchd service:

buildify-opencode-agent install-service
buildify-opencode-agent status
buildify-opencode-agent uninstall-service

Configuration

Config file:

~/.buildify/opencode-agent.json

Show current config:

buildify-opencode-agent config show

Set config values:

buildify-opencode-agent config set key=value [key=value ...]

Common keys:

| Key | Default | Description | | --- | --- | --- | | server | http://localhost:8080 | Buildify Agent Broker URL | | clientId | host name | Agent client ID registered with Broker | | token | empty | Broker auth token | | defaultCwd | ~/projects | Default working directory on the agent machine | | maxConcurrent | 1 | Max parallel tasks | | opencodeBin | opencode | OpenCode executable path | | defaultModel | empty | Default model in provider/model format | | defaultProviderNpm | @ai-sdk/openai-compatible | Default npm package for dynamic providers | | logs | false | Print local agent logs | | acpLogs | false | Print raw OpenCode ACP logs | | reportUpdates | false | Forward raw ACP session/update events to Broker |

Configuration priority:

1. CLI flags
2. Environment variables
3. ~/.buildify/opencode-agent.json
4. Built-in defaults

Environment Variables

| Variable | Description | | --- | --- | | BUILDIFY_SERVER | Broker server URL | | BUILDIFY_TOKEN | Broker auth token | | BUILDIFY_CLIENT_ID | Agent client ID | | BUILDIFY_LOGS | Enable local logs | | BUILDIFY_OPENCODE_ACP_LOGS | Print raw OpenCode ACP logs | | BUILDIFY_OPENCODE_REPORT_UPDATES | Forward raw ACP updates | | BUILDIFY_OPENCODE_BIN | OpenCode executable path | | BUILDIFY_OPENCODE_DEFAULT_MODEL | Default model | | BUILDIFY_OPENCODE_DEFAULT_PROVIDER_NPM | Default provider npm package |

Example:

BUILDIFY_SERVER=http://localhost:8080 \
BUILDIFY_TOKEN=<broker-token> \
BUILDIFY_CLIENT_ID=opencode-local \
buildify-opencode-agent start --logs

CLI Commands

buildify-opencode-agent start [options]
buildify-opencode-agent stop
buildify-opencode-agent status
buildify-opencode-agent install-service
buildify-opencode-agent uninstall-service
buildify-opencode-agent config init
buildify-opencode-agent config show
buildify-opencode-agent config set key=value [key=value ...]

start options:

| Option | Description | | --- | --- | | --daemon | Run in background | | --foreground | Run in foreground | | --server <url> | Override Broker URL | | --token <token> | Override Broker token | | --client-id <id> | Override client ID | | --opencode-bin <path> | Override OpenCode executable | | --default-model <model> | Default model in provider/model format | | --logs | Enable local logs | | --acp-logs | Print raw OpenCode ACP subprocess logs | | --report-updates | Forward raw ACP updates to Broker | | --request-timeout-ms <ms> | HTTP request timeout |

Use In Buildify

Use AgentOpenCodeSubmitTaskNode to submit OpenCode tasks.

Required fields:

• Broker instance
• Client ID matching the running buildify-opencode-agent
• Model selected through ModelSelect
• Prompt
• Working directory (cwd)

Important: cwd is a path on the machine where this agent runs. It is not the Buildify server path. If the directory may not exist, enable “create working directory if missing”.

Provider And Model Configuration

The Buildify ModelSelect value is mapped into the task payload:

• providerId
• model
• providerNpm
• baseURL
• env

The agent builds OPENCODE_CONFIG_CONTENT for OpenCode and starts:

opencode acp --print-logs

For OpenAI-compatible providers, the default provider npm package is:

@ai-sdk/openai-compatible

Example model:

alibaba-cn/qwen3.7-plus

Make sure the selected provider passes a real API key or base URL through env or baseURL.

Debugging

Enable normal logs:

buildify-opencode-agent start --logs

Enable raw ACP logs:

buildify-opencode-agent start --logs --acp-logs

Or:

BUILDIFY_OPENCODE_ACP_LOGS=1 buildify-opencode-agent start --logs

Check daemon/service status:

buildify-opencode-agent status

Use the local ACP debug script:

node debug-acp.mjs \
  --model alibaba-cn/qwen3.7-plus \
  --npm @ai-sdk/openai-compatible \
  --api-key <api-key> \
  --prompt "say hello"

Common Errors

OpenCode directory service failed

OpenCode failed while bootstrapping the project directory or provider directory. Check:

• cwd exists on the agent machine
• the agent process can read and write cwd
• createCwdIfMissing is enabled when needed
• provider config, npm package, and baseURL are valid

Not Found

Usually means OpenCode received a 404 while loading directory/provider resources. Start with --acp-logs and inspect the Error handling request lines.

Provider "<provider>" requires an API key or baseURL

The selected custom provider did not pass credentials to the agent. Check the Buildify ModelSelect env values.

API key was redacted

The agent received a masked placeholder instead of the real API key. Pass the original key value from Buildify.

OpenCode returned no output and no token usage

OpenCode ended without text or usage data. This usually indicates provider authentication, model, quota, or API errors. Enable ACP logs for details.

Development

npm install
npm run typecheck
npm run build
npm run build:dev

Before publishing:

npm run typecheck
npm run build
npm pack --dry-run