From 7ca767de55c50f47bbace107619d79586c1c53d7 Mon Sep 17 00:00:00 2001 From: Dax Raad Date: Mon, 12 Jan 2026 15:43:48 -0500 Subject: [PATCH] core: fix HTTP exception handling order to prevent NamedError from masking HTTP exceptions docs: add OPENCODE_PASSWORD environment variable documentation for basic auth --- packages/opencode/src/server/server.ts | 2 +- packages/web/src/content/docs/cli.mdx | 45 ++++++++++++------------ packages/web/src/content/docs/server.mdx | 10 ++++++ 3 files changed, 34 insertions(+), 23 deletions(-) diff --git a/packages/opencode/src/server/server.ts b/packages/opencode/src/server/server.ts index 05024acde..e79c68558 100644 --- a/packages/opencode/src/server/server.ts +++ b/packages/opencode/src/server/server.ts @@ -83,7 +83,6 @@ export namespace Server { log.error("failed", { error: err, }) - if (err instanceof HTTPException) return err.getResponse() if (err instanceof NamedError) { let status: ContentfulStatusCode if (err instanceof Storage.NotFoundError) status = 404 @@ -92,6 +91,7 @@ export namespace Server { else status = 500 return c.json(err.toObject(), { status }) } + if (err instanceof HTTPException) return err.getResponse() const message = err instanceof Error && err.stack ? err.stack : err.toString() return c.json(new NamedError.Unknown({ message }).toObject(), { status: 500, diff --git a/packages/web/src/content/docs/cli.mdx b/packages/web/src/content/docs/cli.mdx index 357c04ad2..11a1d60d1 100644 --- a/packages/web/src/content/docs/cli.mdx +++ b/packages/web/src/content/docs/cli.mdx @@ -358,7 +358,7 @@ Start a headless OpenCode server for API access. Check out the [server docs](/do opencode serve ``` -This starts an HTTP server that provides API access to opencode functionality without the TUI interface. +This starts an HTTP server that provides API access to opencode functionality without the TUI interface. Set `OPENCODE_PASSWORD` to enable HTTP basic auth (username `opencode`). #### Flags @@ -454,7 +454,7 @@ Start a headless OpenCode server with a web interface. opencode web ``` -This starts an HTTP server and opens a web browser to access OpenCode through a web interface. +This starts an HTTP server and opens a web browser to access OpenCode through a web interface. Set `OPENCODE_PASSWORD` to enable HTTP basic auth (username `opencode`). #### Flags @@ -551,26 +551,27 @@ The opencode CLI takes the following global flags. OpenCode can be configured using environment variables. -| Variable | Type | Description | -| ------------------------------------- | ------- | ------------------------------------------------ | -| `OPENCODE_AUTO_SHARE` | boolean | Automatically share sessions | -| `OPENCODE_GIT_BASH_PATH` | string | Path to Git Bash executable on Windows | -| `OPENCODE_CONFIG` | string | Path to config file | -| `OPENCODE_CONFIG_DIR` | string | Path to config directory | -| `OPENCODE_CONFIG_CONTENT` | string | Inline json config content | -| `OPENCODE_DISABLE_AUTOUPDATE` | boolean | Disable automatic update checks | -| `OPENCODE_DISABLE_PRUNE` | boolean | Disable pruning of old data | -| `OPENCODE_DISABLE_TERMINAL_TITLE` | boolean | Disable automatic terminal title updates | -| `OPENCODE_PERMISSION` | string | Inlined json permissions config | -| `OPENCODE_DISABLE_DEFAULT_PLUGINS` | boolean | Disable default plugins | -| `OPENCODE_DISABLE_LSP_DOWNLOAD` | boolean | Disable automatic LSP server downloads | -| `OPENCODE_ENABLE_EXPERIMENTAL_MODELS` | boolean | Enable experimental models | -| `OPENCODE_DISABLE_AUTOCOMPACT` | boolean | Disable automatic context compaction | -| `OPENCODE_DISABLE_CLAUDE_CODE` | boolean | Disable reading from `.claude` (prompt + skills) | -| `OPENCODE_DISABLE_CLAUDE_CODE_PROMPT` | boolean | Disable reading `~/.claude/CLAUDE.md` | -| `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS` | boolean | Disable loading `.claude/skills` | -| `OPENCODE_CLIENT` | string | Client identifier (defaults to `cli`) | -| `OPENCODE_ENABLE_EXA` | boolean | Enable Exa web search tools | +| Variable | Type | Description | +| ------------------------------------- | ------- | ----------------------------------------------------- | +| `OPENCODE_AUTO_SHARE` | boolean | Automatically share sessions | +| `OPENCODE_GIT_BASH_PATH` | string | Path to Git Bash executable on Windows | +| `OPENCODE_CONFIG` | string | Path to config file | +| `OPENCODE_CONFIG_DIR` | string | Path to config directory | +| `OPENCODE_CONFIG_CONTENT` | string | Inline json config content | +| `OPENCODE_DISABLE_AUTOUPDATE` | boolean | Disable automatic update checks | +| `OPENCODE_DISABLE_PRUNE` | boolean | Disable pruning of old data | +| `OPENCODE_DISABLE_TERMINAL_TITLE` | boolean | Disable automatic terminal title updates | +| `OPENCODE_PERMISSION` | string | Inlined json permissions config | +| `OPENCODE_DISABLE_DEFAULT_PLUGINS` | boolean | Disable default plugins | +| `OPENCODE_DISABLE_LSP_DOWNLOAD` | boolean | Disable automatic LSP server downloads | +| `OPENCODE_ENABLE_EXPERIMENTAL_MODELS` | boolean | Enable experimental models | +| `OPENCODE_DISABLE_AUTOCOMPACT` | boolean | Disable automatic context compaction | +| `OPENCODE_DISABLE_CLAUDE_CODE` | boolean | Disable reading from `.claude` (prompt + skills) | +| `OPENCODE_DISABLE_CLAUDE_CODE_PROMPT` | boolean | Disable reading `~/.claude/CLAUDE.md` | +| `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS` | boolean | Disable loading `.claude/skills` | +| `OPENCODE_CLIENT` | string | Client identifier (defaults to `cli`) | +| `OPENCODE_ENABLE_EXA` | boolean | Enable Exa web search tools | +| `OPENCODE_PASSWORD` | string | Enable basic auth for `serve`/`web` (user `opencode`) | --- diff --git a/packages/web/src/content/docs/server.mdx b/packages/web/src/content/docs/server.mdx index a61d7bae1..a123acb15 100644 --- a/packages/web/src/content/docs/server.mdx +++ b/packages/web/src/content/docs/server.mdx @@ -33,6 +33,16 @@ opencode serve --cors http://localhost:5173 --cors https://app.example.com --- +### Authentication + +Set `OPENCODE_PASSWORD` to protect the server with HTTP basic auth. The username is always `opencode`, and the password is the value of `OPENCODE_PASSWORD`. This applies to both `opencode serve` and `opencode web`. + +```bash +OPENCODE_PASSWORD=your-password opencode serve +``` + +--- + ### How it works When you run `opencode` it starts a TUI and a server. Where the TUI is the