virtual-engineer

🤖 Virtual Engineer

Turn tickets and review events into isolated, traceable AI engineering workflows.

Virtual Engineer is a self-hosted orchestrator that runs AI agents against real repositories while keeping Git and code-review credentials on the host.

🔄 What It Does

Every cycle runs in an ephemeral OpenShell sandbox. The host performs the Git clone and push operations; the sandbox is destroyed after the cycle.

🔌 Supported Systems

Provider configuration, projects, agents, prompts, permissions, runtime settings, costs, and task history are managed from the authenticated Admin UI and stored in SQLite. Provider credentials and other secret fields are encrypted at rest.

🚀 Quick Start

The installer builds the agent and orchestrator images, starts local Keycloak when needed, starts the pinned OpenShell gateway, and launches the orchestrator.

Requirements: Git, curl, OpenSSL, Docker 24+, and a running Docker daemon.

curl -fsSL https://virtual-engineer.dev/install.sh | bash

The installer clones the repository into ./virtual-engineer (or reuses the current directory when it already is a checkout), creates .env, and generates ADMIN_AUTH_SECRET. It supports VE_REF and VE_EXPECTED_COMMIT; see the installer script for reviewable and pinned-install flows.

Managed local Keycloak bootstrap state is stored outside the checkout by default, under $XDG_STATE_HOME/virtual-engineer/local-oidc/ or $HOME/.local/state/virtual-engineer/local-oidc/. This keeps the OIDC secret aligned with the persistent Docker realm when the repository is replaced. Existing data/local-oidc/ files are migrated automatically. Set OPENSHELL_STATE_DIR to use a different persistent location; startup fails when none of OPENSHELL_STATE_DIR, XDG_STATE_HOME, or HOME is set, rather than falling back to the replaceable checkout.

Open the Admin UI at http://127.0.0.1:3100/admin, create the first admin account, and configure the integrations and projects.

For a checkout that already exists:

cp .env.example .env
printf '\nADMIN_AUTH_SECRET=%s\n' "$(openssl rand -hex 32)" >> .env
./scripts/start.sh

The default deployment uses Docker for OpenShell sandboxes. Kubernetes is an experimental alternative; see the Kubernetes deployment guide.

🧭 First Workflow

1. Add and test an agent integration.
2. Add an issue-tracker integration for coding, or a review integration for review tasks.
3. Create an agent and select its model and prompts.
4. Create a project, bind its repository, branch, integrations, and agent, then enable it.

Coding projects pick up assigned tickets. Review projects receive Gerrit stream events or GitLab/GitHub webhook events and do not require an issue tracker.

🛠️ Local Development

Requirements: Node.js 22+, npm 10+, Docker 24+, OpenShell CLI 0.0.83, and a reachable OpenShell gateway.

npm install
cp .env.example .env
printf '\nADMIN_AUTH_SECRET=%s\n' "$(openssl rand -hex 32)" >> .env
npm run db:migrate
npm run build:ui
docker build -f Dockerfile.agent -t virtual-engineer-workspace:latest .
npm run dev

The default agent image ships only Copilot. Build other engines as separate targets when needed, for example docker build -f Dockerfile.agent --target aider -t virtual-engineer-workspace-aider:latest .. With ./scripts/start.sh, select engines in Configuration → System → Agent engines (or set AGENT_ENGINES) and rerun the script to build them.

npm run dev starts the host orchestrator only. Configure OPENSHELL_GATEWAY with an existing CLI profile or OPENSHELL_GATEWAY_ENDPOINT with a reachable endpoint before running it. Use ./scripts/start.sh for the complete containerized path.

See CONTRIBUTING.md for tests, type-checking, linting, and database workflow.

📚 Documentation

• Architecture and data flow
• Kubernetes deployment
• Security architecture and reporting
• Detailed agent reference
• Configuration reference

📄 License

Virtual Engineer is licensed under the GNU General Public License v3.0 only.