Skip to content

Self-host Huly

Issues, chat and docs in one open source workspace, private on your VM.

Deploy on exe.dev

Shelley handles the setup. About 20 minutes.

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

Huly is an open source workspace for teams: an issue tracker in the style of Linear (projects, milestones, sub-issues, time estimates), channels and direct messages, collaborative documents, a planner, a drive and a knowledge base, all linked to each other. It runs as about a dozen containers with CockroachDB, Elasticsearch, Redpanda and MinIO under them, which makes it heavier than a plain issue tracker but still fits on a new exe.dev VM.

This setup keeps Huly private behind exe.dev's HTTPS proxy: only you and the people you share the VM with can reach it, and they sign in with their exe.dev login, with no Huly password to manage. Sharing the VM is all it takes to join your workspace. An agent account works in the same workspace: agents on the VM use the huly command or the MCP server, and agents elsewhere reach the MCP server with a VM token.

What you get#

  • Huly 0.7 at https://my-huly.exe.xyz/, behind exe.dev login, back after a reboot.
  • Sign-in with exe.dev, through Dex: you own a workspace called Team, with Huly's sample projects, and everyone you share the VM with joins it as a member when they first sign in. Huly's password sign-up is off.
  • An agent account and the huly command on the VM, checked by creating, commenting on and closing an issue.
  • The Huly MCP server on port 8100, added to Shelley on the VM and reachable from your computer with two tokens.
  • Nightly backups of all Huly data and its settings in ~/huly/backups.
What's running, and where
Private https://my-huly.exe.xyz/ Huly, for you and the people you share the VM with, signed in with exe.dev
Private https://my-huly.exe.xyz:8100/mcp The MCP server, for agents with an exe.dev VM token and the MCP token
my-huly.exe.xyz exe.dev VM
Huly 0.7 hardcoreeng images v0.7.426 from huly-selfhost: 14 containers in Docker Compose behind nginx :8000Docker volumes huly_v7_*
CockroachDB, Elasticsearch, Redpanda, MinIO Huly's database, search index, event queue and file store, in the same Compose project Docker volumes huly_v7_*
Dex ghcr.io/dexidp/dex v2.46.1: an OpenID Connect provider that signs people in to Huly from exe.dev's login headers
Huly MCP server @firfi/huly-mcp 0.56 (community, MIT) on Node.js, a systemd service :8100
Nightly backup A systemd timer; stops Huly for a minute, keeps a week of copies ~/huly/backups

Deploy with Shelley#

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

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

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

You are done when all of these are true. Check each one yourself:
- Huly 0.7 at `https://my-huly.exe.xyz/`, behind exe.dev login, back after a reboot.
- Sign-in with exe.dev, through Dex: you own a workspace called Team, with Huly's sample projects, and everyone you share the VM with joins it as a member when they first sign in. Huly's password sign-up is off.
- An `agent` account and the `huly` command on the VM, checked by creating, commenting on and closing an issue.
- The Huly MCP server on port 8100, added to Shelley on the VM and reachable from your computer with two tokens.
- Nightly backups of all Huly data and its settings in `~/huly/backups`.

Read the whole recipe, closed details included, and follow "Install by
hand" in order, skipping VM creation; the walkthrough above it is for
the owner. If the reflection integration doesn't return the owner's
email, ask the owner for the email they sign in to exe.dev with. Don't
make the VM public. Don't run Restore or Update. Finish with Huly's URL,
that everyone signs in with "Continue with exe.dev", how to share the
VM to bring in teammates, and the "Let agents work in Huly" section.

Finish with the URLs I should open.

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

Open your workspace#

Open https://my-huly.exe.xyz/ and sign in to exe.dev if asked. On Huly's login page, press Continue with exe.dev. Huly knows you by your exe.dev email and opens Team, the workspace you own. Huly fills a new workspace with two sample projects, Welcome to Huly! and Game Design (Example), so there's something to click on:

  1. The tracker opens first. Press New issue (or C) to file one.
  2. Open an issue to change its status, assign it, add sub-issues, or comment.
  3. The icons in the left bar open the rest: chat, documents, the planner, the drive, contacts. Hover over one to see its name.

Change your name under your profile picture, bottom left, then Settings. Archive the sample projects whenever you like. Your account also has a password, OWNER_PASSWORD in ~/huly/huly_v7.conf, for the email form on Huly's login page; you need it only if exe.dev sign-in ever stops working. Ignore Login with code and Continue as a guest there: neither works on this setup.

Huly's tracker showing the Welcome to Huly project's issues grouped into Todo, Backlog and Done, including three filed by the agent account
The tracker. The issues without an avatar came from the agent account, through the CLI and the MCP server.

Bring your team#

To bring in a teammate, share the VM with them. On your computer:

ssh exe.dev share add my-huly alice@example.com

exe.dev emails them a link. When they open Huly and press Continue with exe.dev, Huly creates their account and adds them to Team as a member; there's no invite or password to pass around. Their name starts out as the part of their email before the @, and they can change it under Settings.

ssh exe.dev share add my-huly team shares with your whole exe.dev team. To remove someone, run ssh exe.dev share remove my-huly alice@example.com; they can no longer reach Huly, and their name stays on what they wrote. Removing them inside Huly isn't enough: while they can reach the VM, signing in adds them back.

Note

Anyone with a Huly account on your server can also create workspaces of their own from the workspace picker. That's harmless on a VM only your team can reach, but it's why sharing the VM is the real gate.

Let agents work in Huly#

Setup created an agent account in the Team workspace, so everything agents do shows up under its name. Its password and the MCP token are in ~/huly/huly_v7.conf, with the rest of the secrets.

On the VM#

The huly command reads that file and talks to Huly as the agent. Try it, on the VM:

huly projects list
huly issues create --project HULY --title "Try the Huly CLI" --priority low
huly issues list --project HULY --limit 3

issues create prints the new issue's identifier, such as HULY-7. Huly's client library also logs some chatter to stderr; add 2>/dev/null to see only the results. Comment on the issue and close it (use your identifier):

huly comments add --project HULY --issue-identifier HULY-7 --body "Done from the CLI."
huly issues update HULY HULY-7 --status Done
huly issues get HULY HULY-7 --json 2>/dev/null | jq -c '.result | {identifier, status}'

The last command shows "status":"Done", and the issue in Huly has the agent's comment. --json makes any command print JSON, and huly --help lists the rest: documents, channels, milestones, labels, the planner, time tracking.

Shelley on this VM also has Huly's MCP server, added as huly, so you can simply ask:

Using the huly MCP server, file an issue in project HULY for each TODO in ~/app/README.md, then list the open issues in HULY.

The MCP server shows a handful of tools (search_tools, get_tool_schema, invoke_tool) that reach all of Huly's operations, about 600 of them, which keeps an agent's context small. Claude Code or Codex on the VM can use the huly command, or add the server the same way (the URL is http://localhost:8100/mcp, with the header Authorization: Bearer and MCP_AUTH_TOKEN from the settings file).

From your computer or another VM#

Port 8100 is behind exe.dev's proxy too, so a remote agent needs two tokens: an exe.dev VM token for the proxy, and the MCP token. Create the VM token on your computer:

ssh exe.dev ssh-key generate-api-key --vm=my-huly --label=huly-agents --exp=90d

Get the MCP token with grep ^MCP_AUTH_TOKEN ~/huly/huly_v7.conf on the VM. Then add the server to Claude Code, on your computer:

claude mcp add --transport http --scope user huly https://my-huly.exe.xyz:8100/mcp \
  --header "X-Exedev-Authorization: Bearer exe1.paste-vm-token-here" \
  --header "Authorization: Bearer paste-mcp-token-here"

Or to Shelley on another VM:

shelley mcp add huly -d "Huly" \
  -H "X-Exedev-Authorization: Bearer exe1.paste-vm-token-here" \
  -H "Authorization: Bearer paste-mcp-token-here" \
  https://my-huly.exe.xyz:8100/mcp

The proxy checks and removes X-Exedev-Authorization; the MCP server checks Authorization. With either one missing, the request is refused.

Warning

The agent can do anything a workspace member can, in every project. Keep huly_v7.conf private, and see Troubleshooting to change the MCP token or the agent's password.

Keep your data#

Everything Huly stores lives in Docker volumes named huly_v7_*. Every night at 04:30 UTC a timer stops Huly for about a minute and packs those volumes, with the settings file, into ~/huly/backups, keeping a week of archives. Keep a copy off the VM: the archive includes huly_v7.conf, so it holds every secret too. On your computer:

scp -r my-huly.exe.xyz:huly/backups .

For updates or hiccups, ask Shelley, or open the instructions below.

The nuts and bolts#

Happy with what Shelley set up? Stop here. Below are the steps it followed, and maintenance for later.

Install by hand

Create the VM#

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

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

A new VM has 2 CPUs, 8 GB of memory and a 25 GB disk, which is enough. All remaining commands run on the VM, as exedev.

Write the settings#

Huly's self-hosting kit, huly-selfhost, has no releases, so this pins a commit, and the Huly version it was tested with. Every setting and secret goes in one file only you can read, ~/huly/huly_v7.conf, which Docker Compose reads as its .env. The owner is the VM owner's exe.dev email, from the reflection integration:

sudo systemctl enable --now docker.service
[ -d ~/huly ] || git clone -q https://github.com/hcengineering/huly-selfhost.git ~/huly
cd ~/huly
git -c advice.detachedHead=false checkout ca3808a57c83518b971343df7d073753f38796ed
owner=$(curl -fsS https://reflection.int.exe.xyz/email | jq -r '.email // empty')
echo "Huly owner: ${owner:?no owner email; set owner=you@example.com and rerun}"
if [ ! -f huly_v7.conf ]; then
  cr=$(openssl rand -hex 24)
  (umask 077; cat > huly_v7.conf <<EOF
# Huly settings and secrets. Docker Compose reads this file as .env.
HULY_VERSION=v0.7.426
DESKTOP_CHANNEL=0.7.426
DOCKER_NAME=huly_v7
HOST_ADDRESS=$(hostname).exe.xyz
SECURE=true
HTTP_BIND=127.0.0.1
HTTP_PORT=8000
TITLE=Huly
DEFAULT_LANGUAGE=en
LAST_NAME_FIRST=true
CR_DATABASE=defaultdb
CR_USERNAME=selfhost
CR_USER_PASSWORD=$cr
CR_DB_URL=postgres://selfhost:$cr@cockroach:26257/defaultdb
REDPANDA_ADMIN_USER=superadmin
REDPANDA_ADMIN_PWD=$(openssl rand -hex 24)
SECRET=$(openssl rand -hex 32)
VOLUME_ELASTIC_PATH=
VOLUME_FILES_PATH=
VOLUME_CR_DATA_PATH=
VOLUME_CR_CERTS_PATH=
VOLUME_REDPANDA_PATH=
# You, the workspace owner. Change the password in Huly if you like.
OWNER_EMAIL=$owner
OWNER_PASSWORD=$(openssl rand -hex 12)
# The agent account, for the huly command and the MCP server
HULY_URL=http://localhost:8000
HULY_WORKSPACE=team
HULY_EMAIL=agent@example.com
HULY_PASSWORD=$(openssl rand -hex 24)
MCP_TRANSPORT=http
MCP_HTTP_HOST=0.0.0.0
MCP_HTTP_PORT=8100
MCP_AUTH_TOKEN=$(openssl rand -hex 32)
HULY_MCP_TELEMETRY=0
DO_NOT_TRACK=1
# Sign-in with exe.dev, through Dex (setup adds HULY_TEAM_INVITE later)
OPENID_CLIENT_SECRET=$(openssl rand -hex 32)
EOF
  )
fi
ln -sfn huly_v7.conf .env
ls -l huly_v7.conf .env

The owner line should show the email you sign in to exe.dev with. If the reflection integration is missing, set owner= to that email yourself and rerun the block. huly_v7.conf should be -rw-------. The agent's address is a placeholder; Huly never sends it mail.

Put Huly behind the exe.dev proxy#

huly-selfhost ships nginx in front of Huly's services. Four files adapt it and add sign-in with exe.dev:

  • nginx-exe.conf replaces its nginx configuration. On port 8000, where exe.dev's proxy connects, browsers get https:// addresses for your VM, while programs on the VM that call http://localhost:8000 get local ones (the VM can't reach its own https:// address). It also sends /dex/ to Dex and has every exe.dev sign-in use a standing invite to Team.
  • dex.yaml sets up Dex, which turns the proxy's X-ExeDev-Email header into an OpenID Connect sign-in, the kind Huly understands.
  • account-start.sh starts Huly's account service. It removes the account API's three ways to sign up with a password, and its way to add another email to your account, which would let anyone who can reach Huly claim a teammate's email before they first sign in, and it waits for Dex, which Huly looks up only once.
  • compose.override.yml, which Docker Compose merges into huly-selfhost's compose.yml, mounts those files, adds Dex, restarts the event queue after a reboot, unpublishes a port nothing outside needs, and hides the sign-up page.

Dex's address is http://my-huly.exe.xyz/dex. Browsers follow it through exe.dev's proxy, which moves them to https. Inside Docker the same name leads to nginx's port 80, so Huly's account service checks sign-ins with Dex without leaving the VM. That port serves Dex's keys and tokens only; the pages that believe the exe.dev headers are on port 8000 alone.

cd ~/huly
cat > nginx-exe.conf <<'EOF'
# Huly behind the exe.dev HTTPS proxy. Requests that arrive as
# localhost:8000 (agents on this VM) get local URLs in /config.json
# and from the account service; everyone else gets https://HULY_HOST.
map $http_host $huly_http { default https://HULY_HOST; localhost:8000 http://localhost:8000; }
map $http_host $huly_ws   { default wss://HULY_HOST;   localhost:8000 ws://localhost:8000; }
# Dex signs people in from the exe.dev proxy's headers. Their name in
# Huly starts out as the part of their email before the @.
map $http_x_exedev_email $exe_name { ~^(?<name>[^@]+)@ $name; default ""; }

# Port 8000, published on 127.0.0.1: where the exe.dev proxy connects.
server {
    listen 8000;
    server_name _;
    client_max_body_size 100M;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    sub_filter_types application/json;
    sub_filter_once off;

    location / {
        proxy_pass http://front:8080;
    }
    location = /config.json {
        proxy_set_header Accept-Encoding "";
        sub_filter "https://HULY_HOST" $huly_http;
        sub_filter "wss://HULY_HOST" $huly_ws;
        proxy_pass http://front:8080;
    }
    # Signing in with exe.dev also joins the Team workspace as a member,
    # so sharing the VM is all it takes to let someone in.
    location = /_accounts/auth/openid {
        absolute_redirect off;
        if ($arg_inviteId = "") {
            return 302 /_accounts/auth/openid?inviteId=HULY_TEAM_INVITE&$args;
        }
        proxy_pass http://account:3000/auth/openid;
    }
    location /_accounts {
        proxy_set_header Accept-Encoding "";
        sub_filter "https://HULY_HOST" $huly_http;
        sub_filter "wss://HULY_HOST" $huly_ws;
        rewrite ^/_accounts(/.*)$ $1 break;
        proxy_pass http://account:3000/;
    }
    location /dex/ {
        proxy_set_header Host $host;
        proxy_set_header X-Huly-Name $exe_name;
        proxy_pass http://dex:5556;
    }
    location /_transactor {
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 1h;
        rewrite ^/_transactor(/.*)$ $1 break;
        proxy_pass http://transactor:3333/;
    }
    location ~ ^/eyJ {
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 1h;
        proxy_pass http://transactor:3333;
    }
    location /_collaborator {
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 1h;
        rewrite ^/_collaborator(/.*)$ $1 break;
        proxy_pass http://collaborator:3078/;
    }
    location /_rekoni {
        rewrite ^/_rekoni(/.*)$ $1 break;
        proxy_pass http://rekoni:4004/;
    }
    location /_stats {
        rewrite ^/_stats(/.*)$ $1 break;
        proxy_pass http://stats:4900/;
    }
}

# Port 80, inside Docker only, where HULY_HOST means this container:
# Huly's account service checks sign-ins with Dex here. Only Dex's
# discovery, keys, token and userinfo; the sign-in pages, which believe
# the exe.dev headers, are on port 8000 alone.
server {
    listen 80;
    server_name _;
    location ~ ^/dex/(\.well-known/openid-configuration|keys|token|userinfo)$ {
        proxy_pass http://dex:5556;
    }
    location / {
        return 404;
    }
}
EOF
cat > dex.yaml <<'EOF'
# Dex: turns the exe.dev proxy's login headers into OpenID Connect for Huly.
issuer: http://HULY_HOST/dex
storage:
  type: memory
web:
  http: 0.0.0.0:5556
oauth2:
  skipApprovalScreen: true
connectors:
  - type: authproxy
    id: exe
    name: exe.dev
    config:
      userIDHeader: X-ExeDev-UserID
      emailHeader: X-ExeDev-Email
      userHeader: X-Huly-Name
staticClients:
  - id: huly
    name: Huly
    secretEnv: OPENID_CLIENT_SECRET
    redirectURIs:
      - https://HULY_HOST/_accounts/auth/openid/callback
EOF
cat > account-start.sh <<'EOF'
#!/bin/sh
# Starts Huly's account service for exe.dev sign-in (mounted into the
# account container; Docker Compose runs it instead of `node bundle.js`).
set -e
cd /usr/src/app

# People get accounts by signing in with exe.dev, so remove the three ways
# to make an account with a password and any email, and the way to attach
# any unverified email to your own account (exe.dev sign-in would then put
# that email's owner into your account): those would let anyone who can
# reach Huly claim a teammate's email before the teammate signs in.
sed -i -e 's/\.\.\.hasSignUp ? { signUp: /...false ? { signUp: /' \
       -e 's/\.\.\.hasSignUp ? { signUpOtp: /...false ? { signUpOtp: /' \
       -e 's/^\( *\)signUpJoin: (0, import_utils6.wrap)(signUpJoin),$/\1\/\/ signUpJoin removed for exe.dev sign-in/' \
       -e 's/^\( *\)addEmailSocialId: (0, import_utils6.wrap)(addEmailSocialId),$/\1\/\/ addEmailSocialId removed for exe.dev sign-in/' bundle.js
if [ "$(grep -c -e '\.\.\.false ? { signUp' -e 'removed for exe.dev sign-in' bundle.js)" != 4 ]; then
  echo "account-start.sh: this Huly version needs a new sign-up patch; not starting" >&2
  exit 1
fi

# Huly looks up Dex only once, at start, so wait up to two minutes for it.
for i in $(seq 60); do
  node -e 'fetch(process.env.OPENID_ISSUER + "/keys").then(r => process.exit(r.ok ? 0 : 1), () => process.exit(1))' && break
  sleep 2
done
exec node bundle.js
EOF
chmod +x account-start.sh
cat > compose.override.yml <<'EOF'
# exe.dev changes to huly-selfhost's compose.yml (merged automatically)
services:
  nginx:
    volumes: !override
      - ./nginx-exe.conf:/etc/nginx/conf.d/default.conf:ro
    ports: !override
      - ${HTTP_BIND}:${HTTP_PORT}:8000
    networks: !override
      huly_net:
        aliases: [HULY_HOST]
      dex_net: {}
  dex:
    image: ghcr.io/dexidp/dex:v2.46.1
    command: [dex, serve, /etc/dex/config.yaml]
    environment:
      - OPENID_CLIENT_SECRET=${OPENID_CLIENT_SECRET}
    volumes:
      - ./dex.yaml:/etc/dex/config.yaml:ro
    restart: unless-stopped
    networks: [dex_net]
  redpanda:
    restart: unless-stopped
  kvs:
    ports: !reset []
  transactor:
    environment:
      - FRONT_URL=https://HULY_HOST
  account:
    command: [/usr/src/app/account-start.sh]
    volumes:
      - ./account-start.sh:/usr/src/app/account-start.sh:ro
    environment:
      - OPENID_DISPLAY_NAME=exe.dev
      - OPENID_CLIENT_ID=huly
      - OPENID_CLIENT_SECRET=${OPENID_CLIENT_SECRET}
      - OPENID_ISSUER=http://HULY_HOST/dex
  front:
    environment:
      - DISABLE_SIGNUP=true
networks:
  dex_net: {}
EOF
sed -i "s/HULY_HOST/$(hostname).exe.xyz/g" nginx-exe.conf dex.yaml compose.override.yml
docker compose config --quiet && echo "compose config OK"

Expect compose config OK.

Start Huly#

The images add up to about 9 GB, so the pull takes a few minutes:

cd ~/huly
docker compose pull --quiet
docker compose up -d
until curl -fsS -o /dev/null http://localhost:8000/config.json; do sleep 5; done
curl -fsS http://localhost:8000/config.json | jq -r .ACCOUNTS_URL
curl -fsS -H "Host: $(hostname).exe.xyz" http://localhost:8000/config.json | jq -r .ACCOUNTS_URL
docker compose ps --format '{{.Service}}: {{.Status}}'

The two addresses should be http://localhost:8000/_accounts and https://my-huly.exe.xyz/_accounts, followed by 15 services, all Up.

Create your workspace and the agent#

The owner account is created with Huly's admin tool, then signs in through Huly's account API and creates the Team workspace, the same way the sign-up page would. The agent account joins it as a member. Last, a standing invite to Team, with no expiry or use limit, goes into the settings file and nginx, for everyone who signs in with exe.dev:

cd ~/huly
set -a; . ./huly_v7.conf; set +a
rpc() { curl -sS -H 'Content-Type: application/json' ${2:+-H "Authorization: Bearer $2"} -d "$1" http://localhost:8000/_accounts; }
until rpc '{"method":"getRegionInfo","params":{}}' | jq -e . >/dev/null 2>&1; do sleep 5; done
./run-tool.sh create-account "$OWNER_EMAIL" -p "$OWNER_PASSWORD" -f "${OWNER_EMAIL%%@*}" -l Owner | tail -1
token=$(rpc "$(jq -nc --arg e "$OWNER_EMAIL" --arg p "$OWNER_PASSWORD" \
  '{method:"login",params:{email:$e,password:$p}}')" | jq -r .result.token)
ws=$(rpc '{"method":"createWorkspace","params":{"workspaceName":"Team"}}' "$token" | jq -r .result.workspaceUrl)
echo "Workspace: $ws"
until rpc '{"method":"getUserWorkspaces","params":{}}' "$token" |
  jq -e --arg ws "$ws" '.result[] | select(.url == $ws) | .status.mode == "active"' >/dev/null; do sleep 5; done
sed -i "s/^HULY_WORKSPACE=.*/HULY_WORKSPACE=$ws/" huly_v7.conf
./run-tool.sh create-account "$HULY_EMAIL" -p "$HULY_PASSWORD" -f Agent -l Bot | tail -1
./run-tool.sh assign-workspace "$HULY_EMAIL" "$ws" | tail -1
sel=$(rpc "$(jq -nc --arg ws "$ws" '{method:"selectWorkspace",params:{workspaceUrl:$ws,kind:"external"}}')" "$token")
echo "$sel" | jq -c '.result | {workspaceUrl, role}'
if ! grep -q '^HULY_TEAM_INVITE=' huly_v7.conf; then
  invite=$(rpc '{"method":"createInvite","params":{"exp":-1,"limit":-1,"role":"USER"}}' \
    "$(echo "$sel" | jq -r .result.token)" | jq -r '.result // empty')
  echo "HULY_TEAM_INVITE=${invite:?no invite}" >> huly_v7.conf
fi
. ./huly_v7.conf
sed -i "s/HULY_TEAM_INVITE/$HULY_TEAM_INVITE/" nginx-exe.conf
docker compose restart nginx

The workspace takes about a minute to build. Expect Workspace: team and then {"workspaceUrl":"team","role":"OWNER"}. The first run-tool.sh downloads Huly's tool image, about 400 MB.

Check exe.dev sign-in#

Huly should offer exe.dev as a way to sign in, send it through the Team invite to Dex, and its account service should reach Dex's keys but not the sign-in pages:

cd ~/huly
curl -fsS http://localhost:8000/_accounts/providers; echo
curl -sS -o /dev/null -w '%{redirect_url}\n' http://localhost:8000/_accounts/auth/openid
docker compose exec -T account node -e '(async () => { for (const p of ["keys", "auth/exe"])
  console.log(p, (await fetch(process.env.OPENID_ISSUER + "/" + p)).status) })()'

Expect [{"name":"openid","displayName":"exe.dev"}], an address ending in inviteId=, a long number and &, then keys 200 and auth/exe 404. If the first line is [], the account service started before Dex answered: run docker compose restart account and check again.

Install the CLI and the MCP server#

huly-mcp and its CLI need a newer Node.js than the VM has, so this installs one in ~/node. A small huly wrapper loads the agent's credentials from the settings file, and a systemd service runs the MCP server on port 8100:

test -x ~/node/bin/node || uvx nodeenv -n 26.13.1 ~/node
export PATH=$HOME/node/bin:$PATH
npm install -g --no-fund --no-audit @firfi/huly-mcp@0.56.0 @firfi/huly-cli@0.54.0 | tail -1
mkdir -p ~/.local/bin
cat > ~/.local/bin/huly <<'EOF'
#!/bin/sh
# huly: Huly's CLI, signed in as the agent account from ~/huly/huly_v7.conf
set -a; . "$HOME/huly/huly_v7.conf"; set +a
PATH="$HOME/node/bin:$PATH" exec "$HOME/node/bin/huly" "$@"
EOF
chmod +x ~/.local/bin/huly
sudo tee /etc/systemd/system/huly-mcp.service >/dev/null <<'EOF'
[Unit]
Description=Huly MCP server for agents
After=docker.service network-online.target

[Service]
User=exedev
EnvironmentFile=/home/exedev/huly/huly_v7.conf
Environment=PATH=/home/exedev/node/bin:/usr/bin:/bin
ExecStart=/home/exedev/node/bin/huly-mcp
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now huly-mcp.service
until curl -s -o /dev/null http://localhost:8100/mcp; do sleep 2; done
shelley mcp add huly -d "Huly: issues, docs and chat" \
  -H "Authorization: Bearer $(sed -n 's/^MCP_AUTH_TOKEN=//p' ~/huly/huly_v7.conf)" \
  http://localhost:8100/mcp
shelley mcp list huly | grep -c '^function'

The last line counts the MCP tools Shelley sees: 6.

Check the agent#

File an issue as the agent, comment on it and close it:

id=$(huly issues create --project HULY --title "Agent check" --json | jq -r .identifier)
huly comments add --project HULY --issue-identifier "$id" --body "Checked by setup." --json | jq -c .
huly issues update HULY "$id" --status Done --json | jq -c .
huly issues get HULY "$id" --json | jq -c '.result | {identifier, title, status}'

The last line should end in "status":"Done". You'll find the issue, with the agent's comment, among the done issues of Welcome to Huly!

Back up nightly#

backup.sh stops Huly, archives its five Docker volumes and the settings files, and starts it again; a consistent copy of CockroachDB, Elasticsearch and MinIO this way takes about 30 seconds plus a minute for Huly to come back:

cd ~/huly
cat > backup.sh <<'EOF'
#!/bin/sh
# Stops Huly for a minute, archives its data volumes and settings, starts it again.
set -eu
umask 077
cd "$(dirname "$0")"
mkdir -p backups
name="huly-$(date +%Y%m%d-%H%M%S).tar.gz"
docker compose stop
trap 'docker compose start >/dev/null' EXIT
docker run --rm \
  -v huly_v7_cr_data:/huly/cr_data:ro -v huly_v7_cr_certs:/huly/cr_certs:ro \
  -v huly_v7_files:/huly/files:ro -v huly_v7_elastic:/huly/elastic:ro \
  -v huly_v7_redpanda:/huly/redpanda:ro \
  -v "$PWD:/config:ro" -v "$PWD/backups:/out" -e owner="$(id -u):$(id -g)" alpine:3 \
  sh -c "mkdir /huly/config && cp /config/huly_v7.conf /config/compose.override.yml /config/nginx-exe.conf \
           /config/dex.yaml /config/account-start.sh /huly/config/ &&
         tar -C /huly -czf /out/$name.tmp . && chown \$owner /out/$name.tmp &&
         chmod 600 /out/$name.tmp && mv /out/$name.tmp /out/$name"
find backups -name 'huly-*.tar.gz' -mtime +7 -delete
echo "backups/$name"
EOF
chmod +x backup.sh
sudo tee /etc/systemd/system/huly-backup.service >/dev/null <<'EOF'
[Unit]
Description=Back up Huly
After=docker.service

[Service]
Type=oneshot
User=exedev
ExecStart=/home/exedev/huly/backup.sh
EOF
sudo tee /etc/systemd/system/huly-backup.timer >/dev/null <<'EOF'
[Unit]
Description=Back up Huly nightly

[Timer]
OnCalendar=*-*-* 04:30
Persistent=true

[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now huly-backup.timer
sudo systemctl start huly-backup.service
systemctl list-timers huly-backup.timer --no-pager
gzip -t backups/*.tar.gz && ls -l backups
printf 'Huly: https://%s.exe.xyz/\n' "$(hostname)"

The timer should list its next run, and backups should hold one archive of roughly 80 MB. Huly is ready: open the URL printed last and press Continue with exe.dev.

Back up and restore

To take a backup now, on the VM (Huly is down for about a minute):

~/huly/backup.sh

Each archive holds the five volumes (cr_data and cr_certs for CockroachDB, files for MinIO, elastic, redpanda) and config/ with huly_v7.conf, compose.override.yml, nginx-exe.conf, dex.yaml and account-start.sh.

Restore#

This replaces all of Huly's data and settings with the archive's, after taking one more backup of the current state. On a new VM, run Install by hand first, then copy the archive into ~/huly/backups. Put the archive's name below, then on the VM:

cd ~/huly
backup=backups/huly-YYYYMMDD-HHMMSS.tar.gz
tar -xzf "$backup" ./config &&
old=$(sed -n 's/^HOST_ADDRESS=//p' config/huly_v7.conf) &&
sed -i "s/$old/$(hostname).exe.xyz/g" config/* &&
./backup.sh &&
docker compose down -v &&
cp config/* . && rm -r config &&
docker compose create &&
docker run --rm -v huly_v7_cr_data:/huly/cr_data -v huly_v7_cr_certs:/huly/cr_certs \
  -v huly_v7_files:/huly/files -v huly_v7_elastic:/huly/elastic \
  -v huly_v7_redpanda:/huly/redpanda -v "$PWD/backups:/in:ro" alpine:3 \
  tar -C /huly -xzf "/in/${backup#backups/}" &&
docker compose up -d &&
sudo systemctl restart huly-mcp.service
shelley mcp rm huly
shelley mcp add huly -d "Huly: issues, docs and chat" \
  -H "Authorization: Bearer $(sed -n 's/^MCP_AUTH_TOKEN=//p' huly_v7.conf)" \
  http://localhost:8100/mcp

The sed line points the restored settings at this VM, so an archive from another VM works. Give Huly a minute, then check that huly issues list --project HULY shows your issues and sign in with exe.dev: the passwords, the Team invite and the MCP token are the archive's, so give remote agents the old MCP token again. The backup taken just before the restore is the newest archive in ~/huly/backups, if you need to go back.

Update

Huly releases often, and huly-selfhost's .template.huly.conf names the version its maintainers tested with. Update to that one, not just the newest image tag. Look at the huly-selfhost commits for changes to compose.yml or the version, then on the VM, back up first:

cd ~/huly
./backup.sh
git fetch -q origin && git -c advice.detachedHead=false checkout origin/main
new=$(sed -n 's/^HULY_VERSION=//p' .template.huly.conf); echo "Updating to $new"
sed -i "s/^HULY_VERSION=.*/HULY_VERSION=$new/; s/^DESKTOP_CHANNEL=.*/DESKTOP_CHANNEL=${new#v}/" huly_v7.conf
docker compose pull --quiet && docker compose up -d
docker image prune -f

Huly upgrades each workspace on first start of the new version, which can take a few minutes (docker compose logs -f workspace shows it). account-start.sh edits the account service's code for this Huly version; if a new one changed that code, the account service stops with needs a new sign-up patch (docker compose logs account). If that or anything else breaks, check out the old commit, put the old version back in huly_v7.conf, and restore the backup you just took.

To update the MCP server and CLI, on the VM:

PATH=$HOME/node/bin:$PATH npm install -g --no-fund --no-audit @firfi/huly-mcp@latest @firfi/huly-cli@latest
sudo systemctl restart huly-mcp.service
Troubleshooting

Start with the containers and their logs. On the VM:

cd ~/huly
docker compose ps
docker compose logs --tail=50 transactor account front nginx
journalctl -u huly-mcp -n 50 --no-pager
  • 502 Bad Gateway right after a start, reboot or backup? Huly needs a minute or two to start all its services. Wait, and reload.
  • Down after a reboot? Run sudo systemctl enable --now docker.service, then docker compose up -d in ~/huly.
  • Huly loads but spins, or says it can't connect? Its live connection is a websocket through nginx. Open Huly at https://my-huly.exe.xyz/, not through an SSH tunnel, and check docker compose logs nginx transactor. If you renamed the VM, the host name in huly_v7.conf, nginx-exe.conf, dex.yaml and compose.override.yml is stale: fix it and run docker compose up -d --force-recreate.
  • Search stops finding new things, or saving fails? The disk may be nearly full: Elasticsearch stops writing above 90%. Check df -h /, remove old images with docker image prune -f, move old backups off the VM, or resize the disk.
  • Slow, or containers restarting? Check memory with free -m and docker stats --no-stream. Huly uses about 4 GB at rest; give the VM more memory if available stays under 1 GB.
  • huly or the MCP server says it can't log in? The agent needs HULY_EMAIL, HULY_PASSWORD and HULY_WORKSPACE from huly_v7.conf, and a running Huly. After changing the file, run sudo systemctl restart huly-mcp.service.
  • Change the MCP token: replace the MCP_AUTH_TOKEN line with a new openssl rand -hex 32, restart huly-mcp, run shelley mcp rm huly and the shelley mcp add line from the install again, and give remote agents the new token.
  • Change the agent's password: sign in to Huly as the agent (its email and password are in huly_v7.conf) in a private window, change it under Settings, put the new one in huly_v7.conf, and restart huly-mcp.
  • No Continue with exe.dev button, or it leads back to the login page? Huly looks Dex up once, when its account service starts. docker compose logs account | grep -i oidc should show Registered OIDC strategy; if it doesn't, run docker compose restart account. Right after Dex restarts, sign-in can bounce back to the login page for about a minute; wait, or restart account.
  • Sign in as someone else? Huly's Sign out only signs you out of Huly: Continue with exe.dev brings back the same exe.dev user. To switch, also sign out of exe.dev at https://my-huly.exe.xyz/__exe.dev/logout.
  • Dex says "Authentication failed"? The request reached Dex without exe.dev's login headers: open Huly at https://my-huly.exe.xyz/ while signed in to exe.dev, not through an SSH tunnel.
  • A Huly invite link shows a sign-up form? Links from Invite to workspace still open Huly's Join page, whose password form doesn't work here. Press Continue with exe.dev on it instead, or skip the link: sharing the VM is enough.

Frequently asked questions#

Is self-hosted Huly free?

Yes. Huly is open source under the Eclipse Public License 2.0, and the self-hosted version has no license key, seat limit or locked features; the paid plans are for Huly's own cloud. You pay only for the VM; see exe.dev pricing. EPL-2.0 lets you use and change Huly freely; if you distribute changed Huly code, you share those changes under the same license.

How much memory does Huly need?

On a new exe.dev VM (2 CPUs, 8 GB), Huly uses about 4 GB at rest, mostly Elasticsearch, Redpanda and CockroachDB, and the containers take about 9 GB of disk. That's comfortable for a small team. Huly recommends 4 CPUs and 16 GB for heavier use; you can resize the VM later without reinstalling.

Can people sign in with their exe.dev login?

Yes, that's how everyone signs in here: Continue with exe.dev on Huly's login page. Huly takes OpenID Connect sign-ins, and exe.dev isn't an OpenID provider, so Dex stands in. Its authproxy connector believes the X-ExeDev-Email header, which exe.dev's proxy sets on every request to a private VM and strips from what browsers send. Dex's sign-in pages are reachable only through nginx on 127.0.0.1:8000, where the proxy connects, so from outside, that header comes from exe.dev. A program on the VM itself can send it too and sign in as anyone, as it could with any app that trusts its proxy; it could read Huly's database anyway. Huly's password sign-up is removed, so new people get in only through exe.dev. Your own account also keeps a password, in ~/huly/huly_v7.conf.

Is there an official Huly API or MCP server?

Huly publishes an API client for JavaScript (@hcengineering/api-client), but no MCP server. This page uses huly-mcp, a community project with over 200 tools for issues, documents, chat and more, and its companion huly command line tool.

Do video calls, the AI assistant and GitHub sync work?

Not in this setup. They are optional services in huly-selfhost that need more parts: LiveKit for calls, an OpenAI key for the assistant, a GitHub app for sync. Issues, chat, documents, the planner, drive and the knowledge base all work without them.

How is Huly different from Plane or Linear?

Plane and Linear are issue trackers. Huly is a whole team workspace: the tracker sits next to channels and direct messages, documents, a planner and a calendar, all linked. That makes it heavier, about 4 GB of memory at rest. If you only want issues, see Plane, Kanboard or the issue tracker overview.

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