01
Start hereWhat actually shipped in v1.17.4
On June 12, 2026, OpenCode's changelog listed v1.17.4 with two additions that, taken together, let you drive it as an embedded HTTP agent instead of just a CLI. First: v2 API endpoints to create and fetch sessions, list a session's questions, and resolve the active location. Second: connector-based authentication flows and support for stored provider credentials. Until now OpenCode was something you ran in a terminal. With an HTTP session API plus auth that lives on the server, you can drive it from your own code — and treat it as a coding agent you embed.
Quick honesty flag (said once, here): "embeddable backend" / "headless agent server" is MY framing of what these endpoints enable — not OpenCode's own label. The verified facts are the endpoints and the connector auth in v1.17.4 (see sources); the architecture pattern is the idea I'm layering on top. And I won't cite GitHub release tags — the repo versions independently (v0.0.x), so the changelog is the canonical place for these feature numbers.
02
Straight from the v1.17.4 changelogWhat's CONFIRMED — the v2 session endpoints
Here is exactly what v1.17.4 added on the API side, nothing inferred: the moving parts of the v2 session surface (the changelog ships create + fetch together, then list-questions and resolve-location), plus the auth change that makes a server deployment practical.
| What v1.17.4 added | Why it matters for embedding |
|---|---|
| v2 endpoint to CREATE a session | Your app starts an agent run over HTTP instead of spawning a CLI process |
| v2 endpoint to FETCH a session | Read back a session's state — the basis for polling a run to completion |
| v2 endpoint to LIST a session's questions | Surface the agent's clarifying questions to YOUR UI, not a terminal prompt |
| v2 endpoint to RESOLVE the active location | Pin where the session is operating, so calls target the right workspace |
| Connector-based auth + stored provider credentials | The server holds the model keys; your calling code never carries them |
That's the whole confirmed surface for this release. The next two sections turn it into something you can actually call: a request flow, and the auth setup.
03
How you actually drive itThe request shape: create -> prompt -> poll
Read this first: the route names and field keys below reflect the v1.17.4 release notes, not a stable published API doc. Pin the exact OpenCode server version you test against and validate every path against your own running server's API reference before you ship — v2 is a fresh surface and the literals can still move. With that caveat set, here's the loop, built only from the endpoints v1.17.4 confirms (create, fetch, list questions). The shape is what's stable; treat a path like
POST /v2/session as a pattern to verify, not a guaranteed literal. You don't watch a terminal anymore — you make HTTP calls and read state back.- Create a session. POST to the v2 create-session endpoint to start an agent run. You get back a session identifier — that's your handle for everything after.
- Send it the work. Hand the session your prompt / task for that run. Your app is now the thing issuing the instruction, where the CLI prompt used to be.
- Poll the session. Call the v2 fetch-session endpoint on an interval to read the run's current state. This replaces watching the terminal scroll — you decide the cadence (a short interval while active, backing off when idle).
- Read its questions. If the agent needs a decision, the list-session-questions endpoint surfaces those. Render them in YOUR interface and feed the answer back, instead of a human typing into a terminal.
- Point it at the right workspace. The resolve-active-location endpoint is the one to reach for in multi-repo or multi-workspace setups — it pins where a session is operating so your calls target the right project instead of a default.
- Stop when it's done. The fetch-session response carries a status/state field; when it transitions to a completed/done value, your poll loop exits and you have your result — entirely over HTTP, no interactive session open. (Confirm the exact field name and terminal value against your server; that detail is version-specific.)
The mental model: your app talks to OpenCode; OpenCode talks to the model. You orchestrate sessions over HTTP; the server runs the agent loop. That separation is exactly what lets one coding agent sit behind many front-ends — and it's the single biggest reason to embed it: one agent, with stored credentials, serving every front-end you build.
04
Why this is the half that makes it deployableThe connector-auth setup (so the server holds the keys)
A session API alone isn't enough to run OpenCode as a service — you'd still be passing provider keys around your calling code. v1.17.4's connector-based auth + stored provider credentials is what closes that gap: the credentials live with the server, and your app authenticates to the server, not to the model provider.
- Configure the connector + store the provider credential on the server. Use the new connector auth flow to attach your model provider, and let the server STORE that credential rather than reading a key from each call. This is the change that makes a long-lived server deployment sane.
- Your calling code authenticates to OpenCode, not to the provider. Your app holds a credential for the OpenCode server only (you still authenticate to the server — this isn't key-free, it's key-relocated). The model-provider key never has to travel with your session calls.
- Keep the key off the client entirely. Because the server resolves the provider via the stored credential, anything calling the session API — a back-end job, an internal tool, another agent — does so without ever seeing the model key.
- Treat the server as the trust boundary. Lock down who can reach the session API the way you'd lock down any service that holds secrets; that's now where the sensitive credential lives.
This is also the part most integrators ship without thinking through. The endpoints let you call the agent; the connector auth is what lets you deploy it without scattering provider keys across every caller.
05
Don't over-engineer itWhen embedding OpenCode is worth it (and when the CLI is still right)
Running OpenCode as an embeddable backend is genuinely useful — but it's not free complexity. Here's the honest decision line, so you reach for it when it pays off and stick with the CLI when it doesn't.
- Embed it when a coding agent needs to sit behind your own surface. Your own UI, an internal tool, a back-end automation, or another agent that needs to delegate coding work — anything where a terminal isn't the interface.
- Embed it when you want one agent serving many callers. A single server with stored credentials, called by several front-ends, beats every caller shelling out to a CLI with its own keys.
- Stick with the CLI for hands-on coding. If it's you, in a terminal, on one machine, the interactive CLI is faster and simpler — the server pattern adds moving parts you don't need.
- Confirm the live API contract before you build. Because this is a fresh v2 surface, read your server's own API reference for the exact routes and payloads, and version-pin so a future change doesn't surprise a deployed integration.
The whole point: v1.17.4 turned OpenCode into something you can put behind software, not just in front of a developer. Use that when the interface isn't a terminal — and don't when it is.
Get the next drop
New AI build guides + the occasional bonus template. No spam, unsubscribe anytime.
By submitting you agree to our Privacy Policy & Terms. Unsubscribe anytime.
You're in — check your inbox to confirm.
Frequently asked questions
What exactly did OpenCode v1.17.4 add?
Per the official changelog dated June 12, 2026, v1.17.4 added v2 API endpoints to create and fetch sessions, list a session's questions, and resolve the active location, plus connector-based authentication flows and support for stored provider credentials. Those are the confirmed additions this guide is built on.
Is OpenCode officially an 'embeddable backend' or 'headless agent server' now?
Those are my framing, not OpenCode's label. What's officially confirmed is the v2 session API and the connector auth. The 'embeddable backend' description is the architecture pattern those endpoints enable — driving OpenCode from your own code over HTTP, with the server holding credentials — which is exactly what makes it usable as a headless coding agent. I'm flagging the distinction so you don't quote a framing as if it were the vendor's wording.
Are the exact endpoint paths and payloads documented here — can I copy them straight in?
No — and this is the one to read before you write integration code. This guide gives you the confirmed endpoints (create/fetch session, list questions, resolve location) and a stable request shape, but NOT invented route strings or field names. A path like
POST /v2/session is a pattern to verify, not a guaranteed literal. Because it's a new v2 surface, the authoritative paths and payloads live in your own running server's API reference. Pin the exact OpenCode version you test against, validate the routes against that build, and only then ship — so a later change doesn't silently break a deployed integration.What's the basic request flow to run a session over HTTP?
Create a session (you get a session id), send it your prompt/task, then poll the fetch-session endpoint to read state until the run completes, surfacing the list-session-questions output in your own UI if the agent needs a decision. Your app talks to OpenCode; OpenCode talks to the model. Confirm the exact routes and field names against your running server's API reference, since this is a new v2 surface.
Why does the connector auth / stored credentials change matter so much?
Because a session API alone would still force you to pass provider keys around your calling code. With connector-based auth and stored provider credentials, the server holds the model credential and your app authenticates to the server instead. That keeps the model key off every caller and is what makes a long-lived server deployment practical rather than a security headache.
Should I cite a GitHub release tag like v1.17.4 from the repo?
No. The OpenCode repository versions independently (it uses v0.0.x style tags), so a GitHub tag won't line up with the v1.17.4 you see in the product changelog. Cite the changelog at opencode.ai/changelog as the canonical source for these feature numbers.
When should I NOT bother embedding OpenCode as a server?
If you're coding hands-on in a terminal on a single machine, the interactive CLI is simpler and faster. The server pattern pays off when a coding agent needs to sit behind your own UI, an internal tool, a back-end job, or another agent, or when you want one agent with stored credentials serving multiple callers. Match the tool to the interface.
Sources · OpenCode changelog — v1.17.4 (June 12, 2026): v2 session endpoints + connector auth / stored credentials (canonical source) · OpenCode — official site / documentation · OpenCode — GitHub repository (note: repo versions independently as v0.0.x; cite the changelog for product feature numbers)