Skip to content

Self-host LoopForge

Your team's coding agents follow the same SOP, and wait for your approval.

Deploy on exe.dev

Shelley handles the setup. About 15 minutes.

Prefer a terminal?
curl -fsSL https://exe.dev/deploy/loopforge/prompt.txt | ssh exe.dev new --prompt=/dev/stdin

LoopForge is Tencent's open-source workspace for a team of coding agents. Instead of asking one agent to "fix this bug" and hoping, you pick an SOP: planning, implementation, review, and testing, each step a role with its own prompt, model, tools, and agent. Runs go step by step in Docker sandboxes and stop at approval gates, where someone reads the report and approves it or sends the work back. Every step's log, tool calls, and artifacts stay on the run page.

Agents can be Codex, Claude Code, Tencent's CodeBuddy, and more. Here LoopForge runs on its own exe.dev VM, private behind your exe.dev login, and Codex and Claude Code reach GPT and Claude through exe.dev's LLM gateway, so there are no API keys to paste.

What you get#

  • LoopForge 0.3.8 at your VM's private URL, behind your exe.dev login and its own accounts, with self sign-up closed.
  • The first account, made by you in the browser, becomes the administrator; your password never passes through Shelley.
  • LoopForge and MySQL back after a reboot.
  • A nightly archive of the database, settings, and workspaces, kept two weeks, with a tested restore.
What's running, and where
Private https://my-loopforge.exe.xyz/ LoopForge, behind your exe.dev login and a LoopForge account
Shared https://my-loopforge.exe.xyz/ Teammates you share the VM with and give a LoopForge account
my-loopforge.exe.xyz exe.dev VM
LoopForge 0.3.8 ghcr.io/tencent/loopforge:0.3.8 in Docker Compose, with sign-up closed :8000~/loopforge/.data and the platform-data volume
MySQL 8.4 In the same Compose project, listening only on the VM the mysql-data volume
Run sandboxes One container per SOP run, started by LoopForge through the VM's Docker
exe.dev LLM gateway GPT and Claude models for Codex and Claude Code, without API keys

Deploy with Shelley#

Click Deploy and Shelley will set up LoopForge on a new VM, then check that it works. No config-file wrangling required.

Prefer a terminal?
curl -fsSL \
  https://exe.dev/deploy/loopforge/prompt.txt \
  | ssh exe.dev new --prompt=/dev/stdin
What Shelley is told
Set up LoopForge on this VM by following the exe.dev recipe at https://exe.dev/deploy/loopforge.md from top to bottom.

The recipe's example VM name is my-loopforge. This VM's name is the output of `hostname`: use it wherever the recipe writes my-loopforge. Skip the step that creates the VM; you are on it.

You are done when all of these are true. Check each one yourself:
- LoopForge 0.3.8 at your VM's private URL, behind your exe.dev login and its own accounts, with self sign-up closed.
- The first account, made by you in the browser, becomes the administrator; your password never passes through Shelley.
- LoopForge and MySQL back after a reboot.
- A nightly archive of the database, settings, and workspaces, kept two weeks, with a tested restore.

Read the whole recipe, including the closed details. For initial setup,
follow "Install by hand" first, skipping VM creation and SSH. Install
exactly the pinned tag, v0.3.8. Don't set MIRROR.
Never open the LoopForge URL and never call /api/auth/register: the first
account becomes the administrator, and the owner must create it. Don't
configure credentials, GitHub, projects, or SOPs yourself.
Keep the VM private. Never run share set-public, and never set
AGENTFLOW_ALLOW_SIGNUP=true. On an existing VM, ask before replacing
anything on port 8000.
Verify: /api/health says ok, /api/auth/setup says needsSetup true, both
containers have the unless-stopped restart policy, the image digest
matches, and the test archive lists loopforge.sql and .env. Do not
reboot, and don't run the restore or update steps.
Finish with https://VM.exe.xyz/ and tell the owner to create their
administrator account now, then follow "Connect Codex and Claude Code".

Finish with the URLs I should open.

Also at /deploy/loopforge/prompt.txt. The recipe it follows is /deploy/loopforge.md.

Create your admin account#

Open https://my-loopforge.exe.xyz/ and sign in to exe.dev. LoopForge asks you to Create the administrator account (switch the page to English with 中 / EN at the bottom): choose a login name and a password. Do it before you share the VM: until the first account exists, anyone who can open the page could take it. Everyone else gets an account from you; sign-up is closed.

You land on the chat home. Its window is in Chinese: 新对话 is a new chat, and the composer has pickers for the agent, model, and project.

Connect Codex and Claude Code#

Keys belong to each account, not to the server. Open Settings (the gear at the bottom left), then Personal settings. Under Models & execution, choose Configure next to Codex:

  • API key: implicit. It's a placeholder: exe.dev adds the real credentials outside the VM.
  • Base URL: https://llm.int.exe.xyz/openai/v1

Click Next, then 保存凭证 (save). Do the same for Claude Code, with implicit and Base URL https://llm.int.exe.xyz/anthropic. The /openai and /anthropic paths matter: LoopForge lists each agent's models from its Base URL, and the gateway's plain address lists GPT models for Claude Code too.

Back on the chat home, pick Codex in the agent menu, a model such as gpt-6.1-sol, and say hi. The reply comes back in a few seconds. In 0.3.8 the chat can't run Claude Code (see the FAQ); SOP roles can.

Try an SOP#

The chat home's first card, 一键体验 (one-click demo), starts a demo SOP that needs no key: a script in a sandbox writes a report, then the run waits for your approval.

A LoopForge run page: Platform check, script and approval, waiting at Needs human judgment with Approve and continue, Add context and rerun this step, and Send back buttons, and a three-step topology below
The demo run, waiting at its approval gate.

Click Approve and continue and the last step runs. Real SOPs work the same way. LoopForge ships generic backend, frontend, bug-fix, and product SOPs under Templates; open their roles under Roles to choose each step's agent and model, then create a requirement in a project and pick an SOP. For code, connect GitHub first (see the FAQ).

Warning

Keep this VM private. LoopForge starts sandboxes through the VM's Docker socket, which is as good as root on the VM, and every account sees every project. Give accounts only to people you'd give a shell.

Bring your team#

On your computer, share the VM:

ssh exe.dev share add my-loopforge teammate@example.com

Then, in LoopForge, open Settings → Platform admin → Accounts, enter a login name, click Generate for an initial password, and Create account. Send them the login and password. Each teammate connects their own agents in Personal settings; through the gateway, their model use is billed to your exe.dev account.

Keep your work#

LoopForge keeps its data in MySQL, a Docker volume, and ~/loopforge/.data (run workspaces). Each night at about 3:30 UTC, a timer dumps the database and archives it with the volume, .data, and the settings in ~/loopforge/.env to ~/backups/loopforge, keeping two weeks. Copy them off the VM too. On your computer:

rsync -av my-loopforge.exe.xyz:backups/loopforge/ ./loopforge-backups/

Keep those copies private: they hold every account's model keys and GitHub tokens.

Setup and upkeep#

No need to read on unless you're curious—or doing it yourself.

Install by hand

On your computer (pick another name if my-loopforge is taken):

ssh exe.dev new --name=my-loopforge
ssh my-loopforge.exe.xyz

All remaining installation commands run on the VM, as exedev.

Get LoopForge#

Start Docker and clone the tested release:

sudo systemctl enable --now docker.service
git clone -q -c advice.detachedHead=false --branch v0.3.8 --depth 1 \
  https://github.com/Tencent/LoopForge.git ~/loopforge
cd ~/loopforge

Configure it#

scripts/configure.sh writes .env with generated database passwords and a session secret. LoopForge listens on port 8000, where the HTTPS proxy sends the VM's address. The two extra lines close sign-up after the first account and mark the session cookie HTTPS-only:

AGENTFLOW_HTTP_PORT=8000 LOOPFORGE_PUBLIC_URL="https://$(hostname).exe.xyz" \
  bash scripts/configure.sh
printf 'AGENTFLOW_ALLOW_SIGNUP=false\nAGENTFLOW_SECURE_COOKIES=true\n' >> .env
grep -E '^(AGENTFLOW_HTTP_PORT|LOOPFORGE_PUBLIC_URL|AGENTFLOW_ALLOW_SIGNUP)=' .env

Expect port 8000, your VM's address, and false.

Start it#

start.sh pulls the pinned images (about 4 GB), starts MySQL and LoopForge, and installs the starter SOPs and the demo project:

LOOPFORGE_YES=1 ./start.sh

It takes a few minutes and ends with ✓ LoopForge is running. LoopForge restarts with Docker, but its MySQL container doesn't, so add that and recreate it:

printf 'services:\n  mysql:\n    restart: unless-stopped\n' > compose.override.yaml
docker compose up -d --wait mysql
docker inspect -f '{{.Name}} {{.HostConfig.RestartPolicy.Name}}' loopforge-mysql-1 loopforge-platform-1
curl -fsS --retry 10 --retry-connrefused --retry-delay 3 localhost:8000/api/health; echo
curl -fsS localhost:8000/api/auth/setup; echo

Expect unless-stopped twice, "status":"ok", and "needsSetup":true. Check the image is the one Tencent released:

docker image inspect --format '{{index .RepoDigests 0}}' ghcr.io/tencent/loopforge:0.3.8

Expect sha256:481ecb6334a21308acb93f164f5dc74f508109d3e108089981a7ea87de095963, the digest in the v0.3.8 release notes.

Set up nightly backups#

The database is dumped in one transaction while LoopForge keeps running. The script runs as root, because sandboxes leave root-owned files in .data, and hands the archives to you:

sudo tee /usr/local/sbin/loopforge-backup >/dev/null <<'EOF'
#!/bin/sh
# Archive LoopForge: a database dump, the platform volume, and .data.
set -eu
cd /home/exedev/loopforge
out=/home/exedev/backups/loopforge
mkdir -p "$out" && chmod 700 "$out"
tmp=$(mktemp -d)
trap 'rm -rf "$tmp"' EXIT
docker compose exec -T mysql sh -c 'MYSQL_PWD="$MYSQL_ROOT_PASSWORD" exec mysqldump -uroot --single-transaction --routines --triggers --add-drop-database --databases loopforge' > "$tmp/loopforge.sql"
docker cp loopforge-platform-1:/data - > "$tmp/platform-data.tar"
tar -czf "$out/loopforge-$(date +%Y%m%d-%H%M).tar.gz" --exclude=.data/cli .env .data -C "$tmp" loopforge.sql platform-data.tar
find "$out" -name 'loopforge-*.tar.gz' -mtime +13 -delete
chown -R exedev:exedev /home/exedev/backups
EOF
sudo chmod 755 /usr/local/sbin/loopforge-backup
sudo tee /etc/systemd/system/loopforge-backup.service >/dev/null <<'EOF'
[Unit]
Description=LoopForge backup
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
UMask=0077
ExecStart=/usr/local/sbin/loopforge-backup
EOF
sudo tee /etc/systemd/system/loopforge-backup.timer >/dev/null <<'EOF'
[Unit]
Description=Nightly LoopForge backup

[Timer]
OnCalendar=*-*-* 03:30:00
RandomizedDelaySec=30m
Persistent=true

[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now loopforge-backup.timer
sudo systemctl start loopforge-backup.service
tar -tzf "$(ls -t ~/backups/loopforge/loopforge-*.tar.gz | head -1)" | grep -cx -e loopforge.sql -e .env
systemctl list-timers loopforge-backup.timer

Expect 2 and a scheduled next run. Downloaded agent CLIs in .data/cli are left out; LoopForge fetches them again.

Create your account#

Open https://<your VM>.exe.xyz/ and carry on from Create your admin account.

Back up and restore

On the VM, take a fresh archive now:

sudo systemctl start loopforge-backup.service
ls -t ~/backups/loopforge | head -3

To restore, set BACKUP to the archive's path. LoopForge stops for about a minute; the database and files are replaced with the archive's:

BACKUP=~/backups/loopforge/loopforge-YYYYMMDD-HHMM.tar.gz
cd ~/loopforge
sudo rm -rf ~/restore && mkdir ~/restore &&
sudo tar -C ~/restore -xzf "$BACKUP" &&
docker compose stop platform &&
sudo cat ~/restore/loopforge.sql | docker compose exec -T mysql sh -c 'MYSQL_PWD="$MYSQL_ROOT_PASSWORD" exec mysql -uroot' &&
sudo cat ~/restore/platform-data.tar | docker cp - loopforge-platform-1:/ &&
sudo rsync -a --delete --exclude=/cli ~/restore/.data/ .data/ &&
docker compose start platform && sudo rm -rf ~/restore

Sign in and check your runs are there. Moving to a new VM? Install there first, copy the archive over with scp, and run the same commands. The new VM keeps its own .env; everyone signs in again.

Update

LoopForge releases often, several times a week lately, and each release pins a new image in compose.yaml. Read the release notes and skip -rc prereleases. Then, on the VM, take an archive and switch to the new tag, replacing VERSION:

sudo systemctl start loopforge-backup.service
cd ~/loopforge
git fetch -q --depth 1 origin tag VERSION &&
git -c advice.detachedHead=false checkout -q VERSION &&
./start.sh pull

./start.sh pull pulls the newly pinned image and restarts LoopForge. Check the digest against the release notes as in "Start it", with the new version, then sign in and check your runs.

LoopForge doesn't migrate data on its own. Each entry in CHANGELOG.md says whether a release needs a migration; apply any file it names, for example:

docker compose exec -T mysql sh -c 'MYSQL_PWD="$MYSQL_PASSWORD" mysql -u loopforge loopforge' < migrations/027_cli_model_catalog.sql
Something stuck?

Ask Shelley, or check on the VM:

cd ~/loopforge
docker compose ps
./start.sh logs
curl -fsS localhost:8000/api/health
  • 502 from the page? LoopForge takes half a minute to start; reload. Still there? Check docker compose ps and the log.

  • LoopForge keeps restarting after a reboot, with lookup mysql errors? MySQL didn't come back. Check compose.override.yaml exists as in "Start it", then run docker compose up -d --wait mysql.

  • The model picker is empty, or the chat says 不支持的执行器 (unsupported executor)? Close the message and choose the agent again; the model list loads after the page. Still empty? Check the agent's Base URL in Personal settings.

  • Claude Code lists GPT models? Its Base URL is missing /anthropic.

  • A run fails? Open the run's WorkerLogs tab, and check your LLM integration.

  • Locked out? Another administrator can reset your password under Platform admin → Accounts. Or, on the VM, set a new one for login NAME:

    cd ~/loopforge && read -rs -p 'New password: ' pw && echo &&
    printf '%s\n' "$pw" | docker compose exec -T platform loopforge-account -user NAME -admin; unset pw
    

Frequently asked questions#

What does it cost?

LoopForge is free and MIT-licensed. You pay for your VM plan and for the models your agents use through the LLM integration. Each run page shows the tokens it used.

Why two logins?

exe.dev's login keeps out everyone you haven't shared the VM with. LoopForge has its own accounts, and each account has its own model keys and GitHub connection, so it keeps its own password. LoopForge can trust a sign-in header only from its own machine, which it isn't in Docker, so this guide doesn't connect the two.

Do I need a CodeBuddy key?

No. Chat and SOP roles can run on Codex or Claude Code through the gateway. A few features only run on Tencent's CodeBuddy: Analyze on a new requirement, notifications, bots, and run evaluation. Add a CodeBuddy key under Personal settings if you want those.

Why is the chat in Chinese?

LoopForge comes from a Chinese team. The settings and management pages switch to English with 中 / EN at the top right; the chat window is Chinese for now. The agents answer in the language you write in.

Can the agents work on my GitHub repositories?

Yes. In Personal settings, choose GitHub and Connect GitHub, then approve the PIN on GitHub. That grants LoopForge's GitHub app repo access for your account; a fine-grained personal access token works too, if you'd rather limit it to some repositories. Then add repositories to a project.

Can I run Claude Code in the chat?

Not with 0.3.8 in Docker: the chat says the server hasn't installed the Claude Code CLI. Choose Codex in the chat. SOP roles can use Claude Code; LoopForge downloads it into the run's sandbox the first time.

Can it run agents on my own machine?

Yes. LoopForge's personal runners connect a laptop or another server with a short-lived binding code, under Runners. We haven't tested them on exe.dev; runs in this guide use sandboxes on the VM.

Updated Nov 15, 2026 · tested end to end Nov 15, 2026 · Markdown · manifest.json · Something wrong? Tell us