AI-EngKit

A reproducible, self-hosted AI engineering workspace for developers and small teams.

AI-EngKit packages OpenCode, OpenChamber, MCP tooling, browser automation, Git workflows, and common build tools into a persistent Ubuntu 24.04 Docker environment.

It is for people who want a ready-to-run AI coding workspace without assembling and maintaining the toolchain by hand. It is not a hosted AI service and is designed for trusted development environments.

Why AI-EngKit?

• One workspace, two interfaces — use OpenCode from the terminal or OpenChamber from a browser.
• Pre-wired engineering tools — CodeGraph, lean-ctx, Playwright, GitHub/GitLab CLI, Docker, and everyday build utilities are included.
• Persistent by default — configuration, sessions, caches, credentials, workspace files, and knowledge data live in separate Docker volumes.
• Operationally manageable — the Admin Dashboard handles environment settings, authentication, project initialization, version inspection, and upgrades.
• Extensible without rebuilding — add apt, Homebrew, or bun packages through environment variables at startup.

Requirements and security boundary

Before installing, have:

• Docker Engine with Compose support
• At least 2 CPU cores, 4 GB RAM, and 30 GB free disk space (8 GB RAM and 100 GB disk recommended)
• An AVX2-capable CPU, required by the OpenCode runtime

Security warning: AI-EngKit mounts the Docker socket so agents and the Admin Dashboard can manage sibling containers. This is a high-trust capability, not a security sandbox. Keep the dashboard and services on a trusted network, change all passwords, and read SECURITY.md before exposing anything beyond localhost.

Quick start

Install the current production channel from main:

curl -fsSL https://raw.githubusercontent.com/tryweb/ai-engkit/refs/heads/main/install.sh | bash

The installer checks system requirements, asks for the OpenChamber and Admin passwords, creates the persistent volumes, and starts the services.

After installation:

• OpenChamber: http://localhost:8000
• Admin Dashboard: http://localhost:8080

The installer-generated .env is the source of truth for your ports and credentials. Do not use the example passwords in a network-accessible deployment; OPENCODE_SERVER_PASSWORD is devonly in the example configuration and should also be replaced.

What is included?

Core workspace

• OpenCode terminal agent and OpenChamber browser UI
• CodeGraph, lean-ctx, and Playwright MCP integrations
• OpenSpec, Superpowers, baked skills, and OpenCode plugin support
• git, gh, glab, Docker Compose, Buildx, Homebrew, bun, Python, ripgrep, jq, tmux, SSH, rsync, and common build tools
• Bundled Playwright Chromium, resolved at runtime through the pw-mcp wrapper

Admin Dashboard

The ai-admin service runs as a separate service from the main ai-dev container, using the same image and shared operational volumes. No separate Admin image is required.

It provides:

• Version and container health overview
• Masked environment-variable editing
• Backup-aware image upgrades with health polling
• Workspace project initialization
• GitHub and GitLab device-code authentication
• Git identity, credentials, and SSH public-key management

See the architecture guide for the service and storage model.

Upgrade and rollback

Upgrade an existing installation with the same supported release flow:

curl -fsSL https://raw.githubusercontent.com/tryweb/ai-engkit/refs/heads/main/upgrade.sh | bash

The upgrade script backs up the compose file and .env, downloads the latest compose configuration, merges newly introduced variables without overwriting custom values, pulls the image, recreates the service, waits for the container to be running, and removes dangling images. Re-running install.sh on an existing installation delegates to this upgrade flow.

To restore a backup:

docker compose down
cp backup_<timestamp>/docker-compose.yml docker-compose.yml
cp backup_<timestamp>/.env .env
docker compose up -d

Configuration

Copy .env.example to .env when configuring a checkout manually. The installer normally creates it for you. The optional package variables below can be added to .env even when they are not present in the example file.

Variable	Default / behavior	Purpose
CHAMBER_PORT	8000	Host port for OpenChamber
ADMIN_PORT	8080	Host port for the Admin Dashboard
OPENCODE_SERVER_PASSWORD	devonly in example	OpenCode API password; replace it
OPENCHAMBER_UI_PASSWORD	chamber in example	OpenChamber password; installer prompts for it
ADMIN_PASSWORD	required	Admin Dashboard password; installer prompts for it
OPENCODE_PLUGINS	bundled plugin list	Comma-separated OpenCode plugins
OPENCODE_PROVIDER	unset	Custom provider JSON injected into opencode.json
WORKSPACE_PATH	named volume	Set a host path for a bind-mounted workspace
BACKUP_RETENTION	5	Number of upgrade backups to retain
APT_PACKAGES	unset	Extra apt packages installed at startup
BREW_PACKAGES	unset	Extra Homebrew packages installed at startup
BUN_PACKAGES	unset	Extra global bun packages installed at startup

Workspace and persistent data

By default, the workspace uses the named workspace volume. To edit files directly with a host IDE:

echo "WORKSPACE_PATH=./workspace" >> .env
docker compose up -d --force-recreate

Important persistent volumes include:

Volume	Container path	Contents
opencode-config	/home/devuser/.config/opencode	OpenCode settings, plugins, agents
opencode-data	/home/devuser/.local/share/opencode	Sessions and conversations
openchamber-data	/home/devuser/.config/openchamber	OpenChamber settings and themes
git-config / ssh-keys	Git and SSH config paths	Git identity, credentials, keys
gh-config / glab-config	GitHub/GitLab CLI paths	CLI authentication state
workspace	/home/devuser/workspace	Projects and source files
lean-ctx-data / lean-ctx-state	lean-ctx data paths	Index, knowledge base, logs, and state

For HTTPS, SSH, multiple accounts, and credential isolation, see Git authentication.

Providers

The Admin Dashboard Providers page (/providers) edits OPENCODE_PROVIDER through structured cards with a raw-JSON fallback per provider, and manages API keys for key-managed providers (currently Opencode Go).

• Provider definitions still live in OPENCODE_PROVIDER in .env and are injected into opencode.json on startup.
• Provider API keys are stored in provider-state/provider-keys.json (directory-mounted into the admin container as /opt/ai-engkit/provider-state, with the file set to 0600), deliberately not in .env so keys never leak through docker inspect.
• The active key for a key-managed provider is written to the opencode auth store (~/.local/share/opencode/auth.json) and applied by restarting the ai-dev container; the page shows a restart-required state and offers the same restart flow as Secrets.
• When a key-managed provider has an existing key in the auth store, the page offers a one-click import before any key is added.

Ports

Container port	Default host mapping	Purpose
3000	${CHAMBER_PORT:-8000}	OpenChamber Web UI
4095	internal	OpenCode service
8080	${ADMIN_PORT:-8080}	Admin Dashboard
8081	development only	Admin Dashboard watch mode

Documentation

• Architecture — services, data flow, storage, and startup behavior
• Tooling — MCP servers, CLI tools, package managers, and extension points
• Security policy — threat model, trust assumptions, and reporting
• Troubleshooting — known issues and fixes
• Git authentication — HTTPS, SSH, gh, and glab
• Changelog — release history

Traditional Chinese guides are available for contributing and security.

Development and testing

Build and run the development stack:

docker compose -f docker-compose.dev.yml build --no-cache
docker compose -f docker-compose.dev.yml up -d

Run the available checks:

./test/run-tests.sh          # tests against a running container
./test/test-admin.sh         # Admin Dashboard integration tests
./test/test-full.sh          # full build, test, and cleanup cycle

See CONTRIBUTING.md before submitting changes.

License

MIT License. See LICENSE.