How to Set Up the OpenCode Agent SDK for Your First Project

In this guide, you'll learn how to install, configure, and run the OpenCode Agent SDK to kick off your first automation project, complete with a real-world case study and a balanced look at its strengths and trade‑offs.

Why You Need the OpenCode Agent SDK: Tackling Common Automation Pain Points

The gaps in traditional CI/CD pipelines

• Static resource allocation. Agents were provisioned weeks in advance. When a burst of PRs arrived, the limited capacity caused flaky tests and missed deadlines.
• Fragmented secret handling. Each job pulled credentials from a separate vault plugin. The configuration drift made it easy to miss a rotation, resulting in a production‑grade outage during a hot‑fix deployment.
• Lack of context awareness. The same generic Docker image was used for both frontend UI tests and heavy data‑processing jobs. The UI tests wasted minutes installing browsers, while the data jobs throttled the CPU.
• Manual orchestration of external tools. Security scans, license checks, and performance benchmarks were invoked via ad‑hoc shell scripts. Updating a script meant touching every Jenkinsfile that referenced it.

1. Scaling spikes. A product launch can double the CI load overnight. Static agents either sit idle most of the time or get saturated when the spike hits.
2. Security compliance. Regulations often demand per‑pipeline secret rotation and audit trails. Keeping that in sync across multiple CI tools is a maintenance nightmare.
3. Heterogeneous workloads. One pipeline might need a Node 18 environment, another a Rust toolchain, and a third a CUDA‑enabled image. Managing a one‑size‑fits‑all pool leads to wasted time and resources.
4. Toolchain sprawl. As teams adopt new linters, static analysis tools, or custom test harnesses, the pipeline definition files become a patchwork of scripts that are hard to test in isolation.

All of this translates to longer feedback loops, higher operational overhead, and a growing risk of human error. That’s where the OpenCode Agent SDK steps in.

Key capabilities the SDK brings

The SDK was built to address exactly these shortcomings. Below are the capabilities that make it a practical replacement for the ad‑hoc scripts and static agents we were fighting with.

• Dynamic agent provisioning. The SDK talks to any container runtime (Docker, containerd, or even Kubernetes) and spins up an agent that matches the declared runtime in your .opencode.yaml. No more pre‑allocating a fixed pool.
• Context‑aware environments. By describing the required toolchain in a declarative block, the SDK pulls the exact image, installs the needed extensions, and caches them for subsequent runs.
• First‑class secret management. Secrets are fetched from supported vaults (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) at runtime, injected as in‑memory variables, and automatically redacted from logs.
• Plug‑and‑play tool adapters. The SDK ships with adapters for common scanners (OWASP ZAP, SonarQube), performance profilers (k6, JMeter), and can be extended with a simple interface implementation.
• Telemetry & audit trail. Every agent execution is logged to a central OpenCode dashboard, complete with timestamps, resource usage, and a hash of the executed script for compliance checks.

pipeline:
  - name: Run integration tests
    runtime:
      image: ghcr.io/opencode/agents/node:18
      resources:
        cpu: 2
        memory: 4GB
    secrets:
      DB_PASSWORD: vault://prod/database/password
    steps:
      - script: |
          npm ci
          npm run test:integration

1. It pulls the node:18 image, adds the npm ci cache layer if it exists, and allocates the requested CPU/memory slice.
2. It contacts the configured vault, retrieves DB_PASSWORD, and injects it as an environment variable that lives only for the duration of the script.
3. It streams the console output back to the OpenCode UI, automatically masking the password wherever it appears.
4. After the script finishes, the agent container is torn down, and the runtime snapshot (including the installed dependencies) is stored as a reusable artifact for the next run.

pipeline:
  - name: Validate model inference
    runtime:
      image: ghcr.io/opencode/agents/python:3.11-cuda
      devices:
        - gpu
    steps:
      - script: |
          pip install -r requirements.txt
          python -m pytest tests/ml/test_inference.py

Because the SDK abstracts the underlying runtime, the same YAML works whether the agent runs on a local Docker daemon, a remote cloud‑native Kubernetes cluster, or a bare‑metal server farm. The portability can reduce the effort required when migrating CI systems.

The SDK includes an optional “one‑click compliance” mode. Enabling the audit: true flag logs each secret request to an immutable storage bucket, and the dashboard presents a compliance matrix that aligns with typical audit checklists. This eliminates the need for additional scripting or manual log shipping.

import opencode.sdk as oc

class BanditAdapter(oc.ToolAdapter):
    name = "bandit"

    def run(self, context):
        result = context.exec(
            ["bandit", "-r", "src/"],
            env={"BANDIT_SEVERITY": "high"}
        )
        if result.exit_code != 0:
            raise RuntimeError("Bandit analysis failed")
        return result.output