Self-hosted AI agent platform

AI Worker

Self-hosted AI agent platform for GitHub and GitLab. Label an issue or merge request, and AI Worker runs coding agents (Cursor CLI / Claude Code / Codex CLI / Gemini CLI / GitHub Copilot CLI) in your environment to implement work or review changes.

Designed for teams that want automation on their own infrastructure—including companies running GitLab Self-Managed—without sending repositories to a third-party hosted agent service.

No clone required for deployment. Only Docker is required. The app image is pulled from Docker Hub.

Image sami1367/ai-worker Source github.com/sami1367/ai-worker

Infrastructure

Self-hosted on your infrastructure

AI Worker is fully self-hosted. You install and run it on hardware you control—your laptop, a workstation, or a dedicated server. Your repositories, credentials, and agent runs stay on your side of the firewall. There is no mandatory third-party hosted agent cloud.

You can run it on a personal computer. For the best day-to-day experience, we recommend a small always-on server (VPS or private cloud). The worker stays online around the clock, so you can label issues or merge requests from your phone—or any device—and automation continues even when your laptop is closed, asleep, or powered off.

Deploy

Quick start

One command — creates the folder, downloads Compose + .env, auto-generates secure secrets, and starts the stack.

mkdir -p ai-worker && cd ai-worker && \
curl -fsSL -o docker-compose.yml \
  https://raw.githubusercontent.com/sami1367/ai-worker/main/docker-compose.yml && \
curl -fsSL -o .env \
  https://raw.githubusercontent.com/sami1367/ai-worker/main/.env.example && \
curl -fsSL https://raw.githubusercontent.com/sami1367/ai-worker/main/scripts/generate-env.sh | bash && \
docker compose up -d && \
curl -fsS http://127.0.0.1:8080/api/v1/health && \
echo && echo "INITIAL_ADMIN_BOOTSTRAP_SECRET=$(cat INITIAL_ADMIN_BOOTSTRAP_SECRET.txt)" && \
echo "Open http://127.0.0.1:8080/setup and paste that secret."

You do not fill secrets by hand. After the command finishes, the bootstrap secret is printed and saved in:

INITIAL_ADMIN_BOOTSTRAP_SECRET.txt
.env — grep INITIAL_ADMIN_BOOTSTRAP_SECRET .env

First run

Create admin

Open http://127.0.0.1:8080/setup
Paste INITIAL_ADMIN_BOOTSTRAP_SECRET
Enter an admin email (used for CodeGraph Pro waitlist signup when configured)
Choose admin username + password (min 12 characters)

Access from a remote server

If AI Worker runs on a remote host, the UI listens on that machine’s 127.0.0.1:8080. Use an SSH tunnel:

ssh -N -L 8080:127.0.0.1:8080 user@SERVER_IP

-L 8080:127.0.0.1:8080 — forwards local port 8080 to the server’s loopback
-N — tunnel only (no remote shell)

Removing `.env` after setup

On first successful start, required secrets are saved on the Docker data volume at /data/config/app-secrets.env. You may delete the host .env afterward if you do not need optional overrides. Keep an offline backup of encryption/session secrets.

Agents

AI providers

AI Worker ships five coding agents in the Docker image. Connect at least one under Providers (http://127.0.0.1:8080/providers): enable it, paste credentials, and set a default. Secrets are encrypted at rest.

Provider	Credential	Env vars
Cursor CLI	Cursor API key	`CURSOR_API_KEY`
Claude Code	Anthropic API key or Claude Code OAuth token	`ANTHROPIC_API_KEY` or `CLAUDE_CODE_OAUTH_TOKEN`
Codex CLI	OpenAI API key	`OPENAI_API_KEY` or `CODEX_API_KEY`
Gemini CLI	Gemini API key	`GEMINI_API_KEY`
GitHub Copilot CLI	Fine-grained GitHub PAT with Copilot Requests	`COPILOT_GITHUB_TOKEN`

Copilot requires a fine-grained PAT with Copilot Requests. Classic ghp_ tokens are not supported. Do not reuse forge GITHUB_TOKEN for the agent.

Semantic index

CodeGraph

CodeGraph builds a local semantic index (.codegraph/) in each workspace and wires MCP into the agent CLIs so agents can navigate code more accurately.

Installed in the image and enabled per repository by default
When enabled, the worker runs codegraph init before an agent if the index is missing
When disabled, .codegraph/ is removed until you turn the option back on
The index is never committed (gitignored from agent publishes)

Integrations

Connect GitHub or GitLab

After admin setup, open Connections at http://127.0.0.1:8080/connections. Use a personal access token for API access. Git clone/push uses that same token over HTTPS by default.

GitHub token

Create a classic or fine-grained PAT, then paste it under Connections → Connect GitHub.

Classic PAT — required scopes

Scope	Why
`repo`	Full private/public repo access (clone, issues, PRs, contents)
`workflow`	Optional; only if agents must edit GitHub Actions workflows

Fine-grained PAT — required permissions

Metadata — Read-only
Contents — Read and write
Issues — Read and write
Pull requests — Read and write
Workflows — Read and write (optional)

GitLab token

Works with gitlab.com and self-managed (e.g. https://git.example.com). Create a personal access token, then under Connections → Connect GitLab set the server URL and paste the token.

Scope	Why
`api`	Recommended. API + repository access for issues, MRs, labels, comments, and HTTPS git
`read_api`	Minimum to list private projects only — not enough for full worker ops

HTTPS git vs optional SSH

AI Worker clones with HTTPS + your token by default. On GitLab self-managed, if clone fails with Git access over HTTP is not allowed, an admin can enable HTTPS git:

GitLab Admin → Settings → General → Visibility and access controls
Enabled Git access protocols → Both or HTTP
In AI Worker, open the repository → Retry clone

A platform SSH key is optional (public key shown on Connections) if you keep GitLab on Only SSH or prefer SSH for git.

Day-to-day

How to use AI Worker

After you connect a forge and enable repositories, work is driven entirely by issue and PR/MR labels in GitHub or GitLab. You do not need a terminal on the AI Worker host for day-to-day tasks.

One-time project setup

Connect GitHub or GitLab under Connections
Wait for discovery (or click Fetch repos)
Enable the repositories you want automated
Optional: Setup labels / Setup webhooks

Repository options

Setting	Default	What it does
PR / MR target branch	Forge default	Branch that new PRs/MRs target; also the clean checkout base
Force-push to target branch	Off	Force-pushes onto the target branch instead of opening a PR/MR
Block new issues while AI PR/MR open	On	Prevents another implement job while an AI-labeled PR/MR is open
Enable CodeGraph	On	Keeps a local `.codegraph/` semantic index
AI provider	Global default	Optional per-repo override of which agent CLI runs

What you do in the forge

Goal	Where	Labels	Result
Implement a change	Open issue	ai	PR/MR or force-push to target
Ask a question	Open issue	ai no-change	Answer in issue comment only
Review a change	Open PR / MR	ai-review	Review comment on the PR/MR

Reference

Label reference

These labels are managed by AI Worker on each connected repository. You normally only add ai, ai + no-change, or ai-review.

Label	Meaning	Who adds it
ai	Queue implement or (with no-change) Q&A	You
no-change	With ai: answer only, no code / no PR	You
ai-working	Worker is processing the issue/PR	Worker
ai-pr	Implement finished; PR/MR created (or force-push landed)	Worker
ai-answered	Q&A finished; answer posted as a comment	Worker
ai-failed	Implement / Q&A failed — check logs	Worker
ai-review	Queue an AI review on an open PR/MR	You
ai-reviewing	Worker is writing the review	Worker
ai-reviewed	Review comment posted	Worker
ai-review-failed	Review failed — check logs	Worker

GitLab & GitHub

Label lifecycles

On GitLab (and GitHub), day-to-day work is a short label lifecycle. You add the trigger label on an issue or merge request; the worker replaces it with status labels as the job runs. The diagrams below show the GitLab-oriented flow (issues → MRs); the same labels apply on GitHub with PRs.

1. Implement an issue

Add ai on an open GitLab issue. The worker checks out the target branch, implements the change, then opens an MR (or force-pushes if that option is on).

You Open issue Add label ai

Worker Fresh checkout ai-working

Success MR created ai-pr or force-push + issue comment

Failure Job failed ai-failed Re-add ai to retry

Confirm the repository target branch (and optional force-push) in the panel
Open a GitLab issue describing the work
Add label ai
Watch: ai → ai-working → ai-pr (or ai-failed)
Review the MR, or the commits on the target branch if force-push is enabled

2. Ask a question — no code changes

Add ai and no-change on an issue. The agent answers in a comment only — no branch, no MR.

You Open issue ai no-change

Worker Processing ai-working no-change

Success Issue comment ai-answered no-change

Failure Ask failed ai-failed no-change

To ask again: keep no-change, remove ai-answered, add ai again.

3. Review a merge request

On an already-open GitLab MR, add ai-review. The worker posts a review comment on the MR.

You Open MR Add ai-review

Worker Writing review ai-reviewing

Success Review posted ai-reviewed

Failure Review failed ai-review-failed

4. Overview of all workflows

Three entry points in GitLab / GitHub map to three outcomes.

Issue: implement ai MR / force-push → ai-pr

Issue: question only ai no-change Comment → ai-answered

MR: review ai-review Review comment → ai-reviewed

Host

Everyday commands

Update

docker compose pull
docker compose up -d

Stop

docker compose down

Support

Troubleshooting

Problem	Fix
`curl` 404 on GitHub raw URL	Repo must be public
Cannot pull image	Try `docker pull sami1367/ai-worker:latest`
Secrets missing / insecure	Re-run `generate-env.sh`
`migrate` fails / CREATE SCHEMA	Password mismatch or old DB volume — see SECURITY docs
Wrong bootstrap secret	Use the value from `generate-env.sh` / `.env`
Git access over HTTP is not allowed	GitLab admin: enable Both or HTTP git protocols, then Retry clone

Legal

License and notices

AI Worker source code and documentation in the repository are licensed under the Elastic License 2.0 (Elastic-2.0). You can use, modify, fork, and self-host AI Worker. You cannot offer it (or a substantial fork) to others as a hosted or managed SaaS. That grant does not relicense proprietary vendor CLIs or third-party container base images.

Elastic-2.0

Project license

View LICENSE on GitHub · NOTICE · Third-party notices · License audit

What Elastic-2.0 allows

Use, modify, and fork AI Worker for your own purposes
Self-host AI Worker on infrastructure you control
Distribute source under the Elastic License 2.0 terms

SaaS restriction

You may not provide AI Worker (or a substantial portion / fork of it) to third parties as a hosted, managed, or multi-tenant service. Self-hosting for your own organization is allowed; offering it as SaaS to others is not.

Earlier Apache-2.0 releases

Prior distributions released under Apache-2.0 remain Apache-2.0 for recipients who already obtained them. Elastic-2.0 applies to new distributions of the current tree.

What it does not cover

Proprietary AI CLIs installed in the Docker image remain the property of their vendors. Dependency licenses (MIT / Apache npm packages, proprietary CLIs) are unchanged — only this repository’s code license changed. Operators must use their own provider credentials and comply with each vendor’s terms.

Component	License / terms	Notes
Cursor Agent CLI	Proprietary (Cursor ToS)	Use your own Cursor credentials
Claude Code	Proprietary (Anthropic terms)	Authenticate and bill under your own credentials
Codex CLI	Proprietary (OpenAI terms)	Use your own OpenAI API key
Gemini CLI	Apache-2.0 (CLI); Google API terms for usage	Use your own Gemini API key
GitHub Copilot CLI	Proprietary (GitHub / Copilot terms)	Fine-grained PAT with Copilot Requests
CodeGraph CLI	MIT	Retain upstream notices when redistributing

Application dependencies (summary)

Direct npm packages used by the app include MIT, Apache-2.0, ISC, and Unlicense components (for example Nuxt, Vue, Drizzle ORM, zod). Retain copyright and license notices when redistributing corresponding source, as required by each license. A full inventory can be regenerated with pnpm licenses list.

AI Worker does not relicense vendor CLIs. Do not resell provider access under a shared account. See THIRD_PARTY_NOTICES.md for the full attribution statement.

Product overview, services, contact, and license

About AI Worker

AI Worker is a self-hosted AI coding assistant for GitHub and GitLab. Label an issue or pull/merge request, and it runs Cursor CLI, Claude Code, Codex CLI, Gemini CLI, or GitHub Copilot CLI in your environment (with optional CodeGraph indexing) to implement work or review changes.

It is built for teams that want automation on their own infrastructure—including organizations running GitLab Self-Managed—without sending repositories to a third-party hosted agent service.

Services

Paid professional services are available on request for companies and development teams. Engagements are scoped per request; no public price list is published here.

AI Worker installation and deployment
Security hardening and configuration
GitHub and GitLab Self-Managed integration
Custom AI workflows, prompts, and integrations
Ongoing maintenance and technical support

Contact and collaboration

GitHub repository	https://github.com/sami1367/ai-worker
Business email	[email protected]
Website	https://vibeplus1.com/
LinkedIn	https://www.linkedin.com/in/sami-rahimi/

Collaboration

Report an issue
Contribute

License

Elastic License 2.0 (Elastic-2.0). You may use, modify, fork, and self-host AI Worker. You may not offer it (or a substantial fork) to others as a hosted or managed SaaS. See the LICENSE file for the full terms.

View LICENSE in the repository ·

Commercial engagement

How to call and order services

Paid professional services for AI Worker are available on request for companies and development teams. Engagements are scoped per request; there is no public price list.

What you can order

Installation and deployment — production-oriented Docker Compose, networking, operational handoff
Security hardening — secret handling, access controls, alignment with your environment
GitHub and GitLab Self-Managed integration — webhooks, tokens, labels, workflow fit
Custom AI workflows, prompts, and integrations — implement/review behavior to your standards
Ongoing maintenance and technical support — after go-live, by agreement

How to request

Open the service request form on vibeplus1.com and describe your environment (GitHub / GitLab Self-Managed, hosting, timeline).
Or email [email protected] with subject AI Worker professional services.
Include: forge (GitHub / GitLab.com / GitLab Self-Managed), where you will host the worker, which services you need, and any security or compliance constraints.
We reply to scope the engagement. Work starts only after you confirm the agreed scope — no fixed public rates.

Prefer a short overview first? AI Worker Enterprise page · or read .

Request services Email to order

Contact channels

Service request form	/service-request
Business email	[email protected]
GitHub	github.com/sami1367/ai-worker
LinkedIn	linkedin.com/in/sami-rahimi

Reach out

Contact

GitHub	sami1367/ai-worker · sami1367
Business email	[email protected]
Website	vibeplus1.com
LinkedIn	linkedin.com/in/sami-rahimi

Maintainers

Developers

Public users should follow the Quick start (no git clone). These notes are for building, publishing, and local Node development.

Publish image to Docker Hub

docker login
./scripts/publish-image.sh          # :latest
./scripts/publish-image.sh 1.0.0    # :1.0.0 and :latest

Build from the repo

docker build -t sami1367/ai-worker:latest .
./scripts/generate-env.sh
docker compose up -d

Local Node development

pnpm install
./scripts/generate-env.sh
docker compose up -d db
pnpm db:migrate
pnpm dev

Do not use placeholder secrets. Further docs live in the repository under docs/DEPLOYMENT.md, docs/ARCHITECTURE.md, docs/SECURITY.md, and docs/BACKUP_RESTORE.md.