Skip to content

Automated documentation update 24081175759 #19

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wcgomes wants to merge 2 commits into from
Closed

Automated documentation update 24081175759 #19

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b6741fa
Automated documentation update [skip ci]
github-actions[bot] Apr 7, 2026
0216c0a
Merge branch 'main' into automated-documentation-update-24081175759
wcgomes Apr 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 10 additions & 65 deletions src/opencode/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,33 +1,9 @@
# opencode Feature

Installs the [opencode](https://opencode.ai) CLI and ensures volume-mounted data directories are owned by the correct user.
# opencode CLI (opencode)

## What the feature does
Installs the opencode AI coding agent CLI and ensures volume-mounted data directories are owned by the correct user.

1. Runs the official installer (`curl https://opencode.ai/install | bash -s -- --no-modify-path`) as the correct user
2. Creates symlink `/usr/local/bin/opencode` to expose the binary on PATH
3. Installs `opencode-fix-permissions` script in `/usr/local/bin/` — automatically executed via `postStartCommand` to fix volume ownership

## Automatic user detection

The feature detects the user automatically using environment variables available during install:

- `_REMOTE_USER` — the user configured in `devcontainer.json` (via `remoteUser`) or fallback to `_CONTAINER_USER`
- `_REMOTE_USER_HOME` — the home directory of that user

If none are available (fallback), uses `vscode` as default.

For common devcontainer base images:

| Image | Default user |
|---|---|
| `mcr.microsoft.com/devcontainers/base:*` | `vscode` |
| `mcr.microsoft.com/devcontainers/universal:*` | `codespace` |
| GitHub Codespaces | `codespace` |

## Required configuration in `devcontainer.json`

The feature can be added without additional configuration. To customize the user, use the `username` option:
## Example Usage

```json
{
Expand Down Expand Up @@ -55,46 +31,15 @@ The feature can be added without additional configuration. To customize the user
}
```

### Available options

| Option | Type | Default | Description |
|---|---|---|---|
| `username` | string | `_REMOTE_USER` or `vscode` | User to install and run opencode for |
| `version` | string | (empty = latest) | Specific version to install (e.g. `1.3.17`) |

### What the feature manages automatically

- **`postStartCommand`** — the feature already declares `postStartCommand: "bash /usr/local/bin/opencode-fix-permissions"` internally, so **no need** to add it to the consumer's `devcontainer.json`
- **Symlink** — `/usr/local/bin/opencode` is created automatically
- **Permissions** — the chown script is generated and invoked automatically after each start

### Mount explanation

| Mount | Purpose |
|---|---|
| `opencode-config` | Configuration files and API keys persistence |
| `opencode-data` | Application data (cache, models, etc.) |
| `opencode-state` | Session state (history, active conversations) |

### Shared volumes between projects

The three named volumes (`opencode-config`, `opencode-data`, `opencode-state`) are global to the Docker daemon. This means:

- **Same project, rebuilds**: data persists between container rebuilds
- **Different projects**: if another devcontainer uses the same volume names, it will access the same data — replicating the behavior of having opencode installed locally on the machine

### What happens without volume mounts?

The feature works perfectly **without** volume mounts. If you don't configure the `mounts`:
## Options

- ✅ The CLI (`opencode`) works normally
- ✅ The binary is installed and symlinked to PATH
- ✅ The `fix-permissions` script runs without errors (it just skips non-existent paths)
| Options Id | Description | Type | Default Value |
|-----|-----|-----|-----|
| username | Username to install opencode for. Defaults to _REMOTE_USER (the container's remote user). | string | - |
| version | Version to install (e.g. 1.3.17). Empty = latest. | string | - |

**Limitation:** Data is stored in the container's ephemeral filesystem. On container rebuild or recreation, configuration, cache, and session state will be **reset** to defaults.

For a persistent experience, we **strongly recommend** adding the volume mounts shown above.

### What is not covered by the feature
---

The `mounts` (volumes) cannot be declared by the feature — they must be specified in the consumer's `devcontainer.json`. This is a limitation of the devcontainer features spec.
_Note: This file was auto-generated from the [devcontainer-feature.json](https://github.com/wcgomes/devcontainer-features/blob/main/src/opencode/devcontainer-feature.json). Add additional notes to a `NOTES.md`._
Loading