core: fix HTTP exception handling order to prevent NamedError from masking HTTP exceptions

docs: add OPENCODE_PASSWORD environment variable documentation for basic auth

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