TrueNAS OpenCode

OpenCode in an authenticated browser terminal with direct, approval-gated access to the TrueNAS 25.10 WebSocket API.

The project is inspired by magnusoverli/opencode, adapted to the Docker-based TrueNAS Apps platform and its JSON-RPC API.

Features

• OpenCode TUI served through ttyd
• Browser-terminal selection copied with the modern Clipboard API
• OpenCode HTTP server for remote clients
• HTTPS and Basic Auth for the browser terminal
• Persistent OpenCode configuration, provider credentials, and sessions
• Read-only TrueNAS diagnostics through MCP
• Approval-gated access to every TrueNAS API method
• Explicit read-only or read/write dataset mounts
• Non-root container with all Linux capabilities dropped
• amd64 images published to ghcr.io/avaneerd/opencode-for-truenas

Security warning

A Full Admin API key gives the AI complete administrative control over TrueNAS. An incorrect instruction, compromised model, malicious file, or unauthorized terminal user could destroy data or make the appliance unavailable.

Do not expose the terminal directly to the internet. Use a dedicated TrueNAS account and API key, a trusted network, HTTPS, a unique terminal password, working backups, and snapshots before risky changes.

TrueNAS installation

The catalog definition is under catalog/ix-dev/community/opencode. It is structured for submission to the TrueNAS Community train. Until that submission is merged, build and publish the image and copy the app directory into a truenas/apps development checkout for catalog testing.

1. Create API credentials

1. Create a dedicated local user such as opencode.
2. Create or select a local group for that user.
3. Grant the group FULL_ADMIN, or a smaller custom privilege if full administration is not required.
4. Generate a user-linked API key owned by that user.
5. Record the key when TrueNAS displays it; it is shown only once.

TrueNAS 25.10 sends API keys using API_KEY_PLAIN. The app therefore requires a verified wss:// connection.

2. Prepare certificates

Select a TrueNAS certificate for the browser terminal. Its hostname should match the name used to open the app.

If the TrueNAS API uses a private CA, paste that CA certificate into TrueNAS CA Certificate. Do not paste the server certificate unless it is itself a trusted CA certificate.

3. Configure storage

The app has two persistent locations:

• /data stores OpenCode state and provider credentials.
• /workspace is OpenCode's primary working directory.

Additional host-path datasets can be mounted below /workspace. Grant the configured container UID/GID access to those datasets. Keep mounts read-only unless OpenCode must edit their contents.

4. Open the portal

Open Web UI from the installed app and authenticate with the configured terminal username and password. Run /connect in OpenCode to configure an AI provider.

Remote clients can connect to http://<truenas-host>:<server-port> using HTTP Basic Auth. The username is opencode and the password is the configured OpenCode Server Password. The server is plain HTTP, so restrict it to a trusted network or put it behind an HTTPS reverse proxy; never expose it directly to the internet.

MCP tools

system_overview reads system information, readiness, alerts, pools, disks, services, and apps.

methods searches the API methods available to the authenticated account and indicates which ones the read-only query tool permits.

query calls methods classified as read-only, such as pool.query, service.query, or system.info. TrueNAS filesystem API methods are deliberately excluded because they would bypass configured dataset mounts.

admin_call can invoke any non-authentication API method and requires a reason describing impact and rollback. The bundled OpenCode configuration prompts before each use.

download_file retrieves an approved TrueNAS host file through the core.download job workflow and stores it under /data/downloads. Downloads use verified HTTPS, are limited to 100 MiB, and never expose the temporary single-use URL.

The client maintains one authenticated WebSocket connection to avoid TrueNAS authentication rate limits. Failed calls are never automatically retried because a mutation could have succeeded before its response was lost.

Container logs include startup, method names, alias resolution, and success or failure type for MCP calls. Parameters and API response bodies are never logged.

Local development

python -m pip install -e ".[test]"
python -m pytest
python -m ruff check .
docker build --build-arg TARGETARCH=amd64 -t truenas-opencode:dev .

For the standalone Compose example:

1. Copy .env.example to .env and fill in its values.
2. Put the API key alone in secrets/truenas-api-key.
3. Put the terminal TLS certificate and key at the configured paths.
4. Set OPENCODE_SERVER_BIND_IP to a trusted interface address if remote clients need access. Its secure default is 127.0.0.1.
5. Run docker compose up --build.

The Compose example requires HTTPS and binds to localhost. Put a trusted TLS reverse proxy in front of it for network access. Private TrueNAS API CAs are supported directly by the catalog app; standalone users can mount a combined CA bundle and set the documented runtime variables in a local Compose override.

Versioning

Repository tags such as v0.1.0 publish matching 0.1.0 and latest image tags. The catalog image tag is immutable and should be updated alongside app_version and the catalog package version.

License

This project is MIT licensed. It installs OpenCode under its MIT license and the official TrueNAS API client under LGPL-3.0.