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.
| Workflow | Input | Result |
|---|---|---|
| Coding | An assigned issue-tracker ticket | Agent commits pushed for review, with feedback cycles |
| Review | A new patchset, merge request, or pull request | Inline findings, discussion replies, and a review decision |
Every cycle runs in an ephemeral OpenShell sandbox. The host performs the Git clone and push operations; the sandbox is destroyed after the cycle.
| Capability | Providers |
|---|---|
| Agent execution | GitHub Copilot, Claude Code, Aider, Goose, Codex, Gemini CLI, OpenCode, Cursor |
| Issue tracking | Redmine, GitLab Issues, GitHub Issues |
| Source control and code review | Gerrit, GitLab Merge Requests, GitHub Pull Requests |
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.
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://raw.githubusercontent.com/savoirfairelinux/virtual-engineer/main/scripts/install.sh | bashThe 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.
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.shThe default deployment uses Docker for OpenShell sandboxes. Kubernetes is an experimental alternative; see the Kubernetes deployment guide.
- Add and test an agent integration.
- Add an issue-tracker integration for coding, or a review integration for review tasks.
- Create an agent and select its model and prompts.
- 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.
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 devnpm 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.
- Architecture and data flow
- Kubernetes deployment
- Security architecture and reporting
- Detailed agent reference
- Configuration reference
Virtual Engineer is licensed under the GNU General Public License v3.0 only.