Getting Started with opencode-rust: A Rust-Based AI Coding Agent

What is opencode-rust?

opencode-rust is an open-source AI coding agent implemented in Rust. It provides a terminal user interface, one-shot command execution, an HTTP server, Web support, and ACP integration for local AI-agent workflows.

The engine combines sessions, tool execution, MCP, LSP, provider routing, SQLite storage, and a TypeScript plugin bridge. It runs without Docker or another container runtime. Rust is used to keep resource usage bounded through streamed request bodies, SQLite-backed conversation history, cached tool schemas, and pooled per-directory state with LRU and TTL eviction.

Choose an installation method

All supported installation methods provide the opr command, but the command behaves differently depending on how it was installed.

Install with npm

npm supports Linux, macOS, and Windows and downloads a prebuilt binary package for the current platform. It does not compile the project during installation.

npm install -g opencode-rust

The npm launcher is a Node script that dispatches commands to the engine. The available platform packages include macOS ARM64 and x64, Linux x64 and ARM64 GNU builds, Linux x64 musl, and Windows x64 MSVC.

Install with Homebrew

On macOS or Linux, install the Homebrew formula with:

brew install vakandi/tap/opencode-rust

This installs opr without placing an opencode binary in the Homebrew prefix, so it does not shadow the upstream OpenCode CLI. Homebrew builds from source and therefore installs a Rust toolchain as a build dependency.

Build from source

Clone the repository and run the installer:

git clone https://github.com/vakandi/opencode-rust.git
cd opencode-rust
./install.sh

The installer builds the release binary and installs opr along with agent shortcuts. It fingerprints Rust sources and the Cargo manifest files, so an unchanged project does not rebuild. Use --force to rebuild regardless.

When using Homebrew or the source installer, opr is the engine binary itself. Use an explicit subcommand when passing flags:

opr tui --some-flag

With npm, the launcher dispatches flags to the TUI, so opr --some-flag is interpreted differently.

Prepare the environment

Node.js 18 or newer is required for the plugin bridge and for launching MCP servers through npx, regardless of the installation method.

You also need a provider key before the first run. For example, set an Anthropic key in your shell:

export ANTHROPIC_API_KEY=sk-ant-...

Use the provider and credential configuration supported by your OpenCode setup. Keep keys out of source control and shell history where possible.

Run your first session

Start the interactive TUI

Launch the terminal interface with:

opr

The TUI is the default interactive surface. It displays the active agent and model, streams assistant output, and provides command completion through the / popup.

Run a single prompt

For an automated prompt that runs to completion, use run:

opr run "check this repo for risks"

Unlike a simple provider call, run drives the full session prompt loop. Tools execute, awaited subagents complete, and background work is drained before the process exits.

Start the HTTP server

To expose the engine through its HTTP server, run:

opr serve --port 3000

The server uses the same session engine and supports the project's HTTP, streaming, and agent infrastructure.

Use named agents

The TUI includes built-in build and plan agents. The build agent is the default full-access development agent, while plan is intended for read-only analysis and exploration. Press Tab to switch agents in the TUI.

The source installer also creates shortcuts for named agents:

gilfoyle "fix this failing test"
setbon "write 5 ad hooks"
googlebot "audit my meta tags"

These shortcuts run one prompt with the corresponding --agent value. Calling one without a prompt prints usage information to standard error and exits with status 2.

Additional agents can be configured in your OpenCode configuration and in the oh-my-opencode agent stores at ~/.omo/omo.jsonc or ~/.config/omo/omo.jsonc. Agent configuration from these locations can override a plugin default, and agents are matched using canonical slugs even when their display names differ.

Configure projects and sessions

Configuration files are merged while searching upward from the working directory. Supported project-level names are:

• opencode.jsonc
• opencode.json
• .opencode/opencode.jsonc
• .opencode/opencode.json

The global default configuration is stored under ~/.config/opencode/opencode.json or its JSONC equivalent. Agent definitions may also be stored in the oh-my-opencode locations described above.

Sessions are stored in SQLite and support creation, continuation, forking, import and export, and parent-child relationships. To inspect the database location, use:

opr db path

To inspect other runtime locations, including the data directory used by the proxy pool, use:

opr debug paths

Use MCP tools

opencode-rust supports MCP over stdio and HTTP. MCP servers are loaded from configuration, started in parallel under a 90-second startup ceiling, and registered in the same per-turn tool registry used by the agent.

This means tools exposed by an MCP server can reach the model and execute as part of an agent turn. Ensure Node.js and the required MCP server packages are available before starting a session.

The project uses newline-delimited JSON for MCP stdio transport. This is distinct from LSP's Content-Length framing, so MCP server configurations should target MCP-compatible transports and definitions.

Ensure background work completes

The run command accepts a timeout for background-task draining:

opr run --wait-background-timeout 120 "run the requested task"

After the main turn, the engine waits for the session to become idle, streams child frames recorded by oh-my-opencode, and checks continuation state. The default timeout is 120 seconds.

The drain fails open rather than hanging: missing databases, missing ledgers, corrupt JSON, and stale active entries are treated as having no remaining work. Use a shorter or longer timeout when your workflow requires different limits.

Configure the rotating proxy

The engine includes a local HTTP and CONNECT forwarder that rotates through residential proxy candidates. It selects the oldest-used upstream approximately every 120 seconds, probes candidates before use, and quarantines rejected entries.

The default pool file is located at:

• macOS: ~/Library/Application Support/opencode/proxy-pool.txt
• Linux: ~/.local/share/opencode/proxy-pool.txt
• Windows: %LOCALAPPDATA%\opencode\proxy-pool.txt

Set OPENCODE_PATHS_ROOT to move the data location. The resulting pool path is $OPENCODE_PATHS_ROOT/opencode/proxy-pool.txt.

Entries use a host and port, with optional credentials and metadata:

198.51.100.10:8080
203.0.113.24:1080
198.51.100.31:3128:myuser:mypass
203.0.113.77:8000 | note:rotates hourly

Keep the file to bare entries. Although lines beginning with # are shown in some examples as comments, the parser does not implement comment syntax; such lines are ignored as malformed entries. Failed candidates and ownership information are maintained in sibling proxy-quarantine.json and proxy-claims.json files.

Proxy startup must be performed through opencode_proxy::start() rather than by exporting proxy variables manually. The client must receive the proxy configuration before the provider registry is built. An empty or unreadable pool returns an error instead of starting a listener that would fail every request.

Explore the command surface

The CLI includes commands for interactive use, sessions, services, configuration, authentication, agents, debugging, MCP, data transfer, and maintenance:

tui      attach   run      serve    web      acp      models
session  stats    db       config   auth     agent    debug
mcp      export   import   github   pr       upgrade  uninstall
generate version

Useful run options include --continue, --session, --fork, --agent, --format, --title, --dir, --port, --variant, --thinking, and --wait-background-timeout.

Development and verification

If you are working on the repository, run the workspace tests and checks with:

cargo test --workspace
cargo build --release --bin opencode
cargo clippy --workspace --all-targets

The repository is organized into crates for the CLI, server, sessions, agents, tools, providers, MCP, plugins, LSP, storage, TUI, permissions, paths, proxying, and related utilities. Per-crate documentation is available in the docs/ directory.

Conclusion

opencode-rust provides a Rust-based OpenCode engine with an interactive TUI, complete session execution, configurable agents, MCP and plugin integration, SQLite storage, and HTTP access. Start with npm, Homebrew, or a source build, configure a provider key, and use opr, opr run, or opr serve according to your workflow.

The project is released under the MIT license and is not affiliated with the OpenCode team.