Skip to content

A web UI for Garage, on its own VM

Buckets, keys, and files of your Garage in a browser, on a VM of its own.

Deploy on exe.dev

Shelley handles the setup. About 10 minutes.

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

Garage Web UI puts your Garage object store in a browser: cluster health, buckets and their quotas, keys and who can use what, and a file browser with uploads, downloads, and image previews. Here it runs on a small VM of its own, behind exe.dev login and a list of allowed emails. It reaches your Garage VM through two exe.dev integrations that hold the credentials, so this VM keeps no secrets and neither VM opens anything to the internet.

Garage Web UI browsing uploads/2026/11 in the app-data bucket, with thumbnails of four PNG images
Browsing a bucket on the Garage VM from the UI VM. The thumbnails come straight from Garage over S3.

You need a Garage VM set up with the Garage page first. The UI uses its admin API (port 3903) and its S3 API at https://my-garage.exe.xyz/, which that page's nginx serves on port 8000.

What you get#

  • Garage Web UI at https://my-garage-ui.exe.xyz/, open only to the exe.dev emails in ~/garage-webui/allowed-emails.
  • Buckets, keys, permissions, and files of your Garage VM, browsed and changed from the browser.
  • An admin token that expires in a year and can't create other tokens or change the cluster layout.
  • No secrets on this VM. The admin token and exe.dev's key live in two exe.dev integrations, which add them at the edge.
What's running, and where
Private https://my-garage-ui.exe.xyz/ the web UI, for the exe.dev emails you list
my-garage-ui.exe.xyz exe.dev VM
Garage Web UI 1.1 khairul169/garage-webui, one Go binary run by systemd, on localhost :3909
nginx Lets in only the emails you list, and hands the UI's S3 requests to the garage-s3 integration :8000
Two exe.dev integrations garage-admin and garage-s3 reach the Garage VM, holding its admin token and exe.dev's key
Your Garage On its own VM, set up with the Garage page; nothing changes there

Deploy with Shelley#

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

Have these ready; Shelley asks for them:

  • GARAGE_VM: the name of the VM that runs Garage, such as my-garage
Prefer a terminal?
curl -fsSL \
  https://exe-staging.dev/deploy/garage-webui/prompt.txt \
  | ssh exe.dev new --prompt=/dev/stdin

When it's done, run this on your computer (only you can):

ssh exe.dev share add my-garage-ui teammate@example.com   # then add them to allowed-emails
ssh exe.dev integrations remove garage-admin   # cut the UI off from Garage
What Shelley is told
GARAGE_VM=<fill-this-in>

Set up Garage Web UI on this VM by following the exe.dev recipe at https://exe-staging.dev/deploy/garage-webui.md?via=deploy from top to bottom.

The values at the top of this message are mine:
- GARAGE_VM: the name of the VM that runs Garage, such as my-garage
Ask me for any that still say <fill-this-in> before you need them.

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

You are done when all of these are true. Check each one yourself:
- Garage Web UI at `https://my-garage-ui.exe.xyz/`, open only to the exe.dev emails in `~/garage-webui/allowed-emails`.
- Buckets, keys, permissions, and files of your Garage VM, browsed and changed from the browser.
- An admin token that expires in a year and can't create other tokens or change the cluster layout.
- No secrets on this VM. The admin token and exe.dev's key live in two exe.dev integrations, which add them at the edge.

Read the whole recipe, including the closed details. Follow "Install by
hand" on this VM. The step "Connect it to Garage" runs on the owner's
computer, not here: give the owner those commands with GARAGE_VM and this
VM's name filled in, and wait until they say they ran them. Check with
`curl -s https://reflection.int.exe.xyz/integrations` that garage-admin
and garage-s3 are attached (if the owner picked other names, use those).
Then continue with "Point it at Garage" and the checks.
Allow only the owner's email, read from the reflection integration; if
that fails, ask the owner for it. Leave this VM and the Garage VM private,
and don't change anything on the Garage VM.

Finish with the URLs I should open and these commands, which only I can run, from my own computer (with this VM's name in them):
  ssh exe.dev share add my-garage-ui teammate@example.com   # then add them to allowed-emails
  ssh exe.dev integrations remove garage-admin   # cut the UI off from Garage

Also at /deploy/garage-webui/prompt.txt. The recipe it follows is /deploy/garage-webui.md.

Open the UI#

When Shelley finishes, open https://my-garage-ui.exe.xyz/ and sign in to exe.dev. The dashboard shows the cluster's health and use; Buckets lists every bucket with its size and object count, and Browse opens its files. Keys creates access keys and shows their secrets, and a bucket's Permissions tab gives keys read, write, or owner rights.

Only the emails in ~/garage-webui/allowed-emails get in, even if you share the VM. To let a teammate in, share the VM with them, add a line with their email and 1;, then reload nginx:

echo 'teammate@example.com 1;' >> ~/garage-webui/allowed-emails
sudo systemctl reload nginx

Anyone on the list can read and delete every file and see every key's secret, so keep it short. Sharing this VM doesn't give anyone access to the Garage VM itself.

How it reaches Garage#

exe.dev VMs don't share a network, and the Garage VM is private. Two VM-to-VM integrations connect them. Each gives this VM an address under int.exe.xyz; exe.dev adds a key for the Garage VM at the edge, and passes the request to that VM's proxy:

Integration From this VM Reaches Adds
garage-admin https://garage-admin.int.exe.xyz the admin API, port 3903 the Garage admin token, replacing whatever the UI sends
garage-s3 https://garage-s3.int.exe.xyz the S3 API, nginx on port 8000 nothing; S3 requests are signed with a Garage key

The UI calls the admin API at its int.exe.xyz address directly. S3 needs one more step, because a signed S3 request covers the host name: the integration delivers it with Host: my-garage.exe.xyz, so the UI has to sign for that name. The UI sends S3 requests for http://my-garage.exe.xyz to a small nginx on 127.0.0.1:3128, as its HTTP proxy, and nginx hands them to https://garage-s3.int.exe.xyz. It refuses any other host.

Neither credential is on this VM, so someone with a shell here can use Garage through the UI's integrations but can't take the admin token elsewhere. Removing the garage-admin integration cuts the UI off at once. The integrations reach only the Garage VM, and requests arrive there with an X-Exedev-Source-Vm header naming this VM.

What the UI can do#

The admin token this page makes is limited to what the UI needs for buckets and keys, and expires in a year:

GetClusterHealth GetClusterStatus GetClusterLayout GetNodeInfo
ListBuckets GetBucketInfo CreateBucket UpdateBucket DeleteBucket
AddBucketAlias RemoveBucketAlias AllowBucketKey DenyBucketKey
ListKeys GetKeyInfo CreateKey ImportKey DeleteKey

It can't create admin tokens or change the cluster layout, so the Cluster page shows the nodes but can't assign or connect them. To allow that, add UpdateClusterLayout,ApplyClusterLayout,RevertClusterLayout,ConnectClusterNodes to --scope when you renew the token.

For files, the UI reads each bucket's first key from the admin API and uses it over S3, so it sees every bucket that has a key. Uploads go in one request per file; for big files or whole folders, rclone and aws s3 sync on the Garage page are faster. A bucket's "Share" link points at Garage's website endpoint and only means something for website buckets.

Renew the token#

The Garage admin token expires after a year. To replace it, or to cut the UI off at once, remove the old token and its integration on your computer:

ssh my-garage.exe.xyz garage admin-token delete --yes garage-webui
ssh exe.dev integrations remove garage-admin

Then run the first command of Connect it to Garage again. Nothing changes on this VM. garage admin-token list on the Garage VM shows when the token expires.

Use Tailscale instead#

If both VMs are on your Tailscale network, the UI can reach Garage directly and needs no integrations or forward proxy. On the Garage VM, set api_bind_addr = "[::]:3903" under [admin] in /etc/garage.toml and restart Garage; then, in this VM's /etc/garage-webui/env, use API_BASE_URL=http://my-garage:3903 and S3_ENDPOINT_URL=http://my-garage:3900, put the admin token from "Connect it to Garage" in API_ADMIN_KEY, and drop the HTTP_PROXY line. That token then sits on this VM. The admin API is then open to your whole tailnet, guarded by its tokens; use Tailscale's access rules to narrow it. We haven't tested this variant.

The nuts and bolts#

Install by hand

Create a VM#

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

ssh exe.dev new --name=my-garage-ui
ssh my-garage-ui.exe.xyz

The remaining commands run on this VM, as exedev, except "Connect it to Garage", which runs on your computer.

Install the UI#

sudo curl -fsSL -o /usr/local/bin/garage-webui \
  "https://github.com/khairul169/garage-webui/releases/download/1.1.0/garage-webui-v1.1.0-linux-$(dpkg --print-architecture)"
sudo chmod 755 /usr/local/bin/garage-webui
sudo mkdir -p /etc/garage-webui
mkdir -p ~/garage-webui
email=$(curl -fsS https://reflection.int.exe.xyz/email | jq -r .email)
[ -s ~/garage-webui/allowed-emails ] || echo "$email 1;" > ~/garage-webui/allowed-emails
cat ~/garage-webui/allowed-emails

It should print your email, then 1;. If not, put you@example.com 1; in ~/garage-webui/allowed-emails yourself.

Connect it to Garage#

On your computer, make a narrow Garage admin token and hand it straight to a new exe.dev integration, then add a second integration for S3. Set the two VM names first:

GARAGE_VM=my-garage
UI_VM=my-garage-ui
ssh $GARAGE_VM.exe.xyz garage admin-token create --expires-in 365d -q \
  --scope GetClusterHealth,GetClusterStatus,GetClusterLayout,GetNodeInfo,ListBuckets,GetBucketInfo,CreateBucket,UpdateBucket,DeleteBucket,AddBucketAlias,RemoveBucketAlias,AllowBucketKey,DenyBucketKey,ListKeys,GetKeyInfo,CreateKey,ImportKey,DeleteKey \
  garage-webui |
  ssh exe.dev integrations add http-proxy --name garage-admin \
    --target https://$GARAGE_VM.exe.xyz:3903/ --peer --bearer=- --attach vm:$UI_VM
ssh exe.dev integrations add http-proxy --name garage-s3 \
  --target https://$GARAGE_VM.exe.xyz/ --peer --attach vm:$UI_VM

The token never appears on screen or on either VM's disk outside Garage; exe.dev stores it and adds it to every request through garage-admin. --peer makes exe.dev generate a key for the Garage VM, which it keeps too. The scopes are in What the UI can do. Integration names are per account: for a second Garage, pick other names and use them below.

Point it at Garage#

Back on this VM. The UI's settings, with no secrets in them; set GARAGE_VM to your Garage VM's name:

GARAGE_VM=my-garage
sudo tee /etc/garage-webui/env >/dev/null <<EOF
HOST=127.0.0.1
PORT=3909
CONFIG_PATH=/dev/null
API_BASE_URL=https://garage-admin.int.exe.xyz
API_ADMIN_KEY=added-by-exe.dev
S3_ENDPOINT_URL=http://$GARAGE_VM.exe.xyz
S3_REGION=garage
HTTP_PROXY=http://127.0.0.1:3128
EOF
curl -s https://garage-admin.int.exe.xyz/v2/GetClusterHealth | jq -r .status

That should print healthy. CONFIG_PATH=/dev/null keeps the UI from looking for a Garage config file, and API_ADMIN_KEY is a placeholder that the garage-admin integration replaces.

Then the small forward proxy for S3. It accepts only the Garage VM's name and sends those requests to the garage-s3 integration:

sudo tee /etc/nginx/conf.d/garage-s3-forward.conf >/dev/null <<EOF
# Garage Web UI signs S3 requests for $GARAGE_VM.exe.xyz; send them to the
# garage-s3 integration, which delivers them to that host.
map \$http_host \$garage_s3_ok {
    default              0;
    "$GARAGE_VM.exe.xyz" 1;
}
server {
    listen 127.0.0.1:3128;
    resolver $(awk '/^nameserver/ {print $2; exit}' /etc/resolv.conf);
    set \$garage_s3 garage-s3.int.exe.xyz;
    client_max_body_size 0;
    proxy_request_buffering off;
    proxy_buffering off;
    location / {
        if (\$garage_s3_ok = 0) { return 403; }
        proxy_pass https://\$garage_s3;
        proxy_set_header Host \$garage_s3;
        proxy_http_version 1.1;
        proxy_ssl_server_name on;
        proxy_ssl_name \$garage_s3;
        proxy_ssl_verify on;
        proxy_ssl_verify_depth 4;
        proxy_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;
    }
}
EOF
sudo nginx -t && sudo systemctl enable --now nginx && sudo systemctl reload nginx
sleep 2
curl -s -x http://127.0.0.1:3128 http://$GARAGE_VM.exe.xyz/ | head -n 1

The last command should print the start of the Garage VM's placeholder website (the Garage page puts it there), which shows requests get through.

Start the UI#

sudo tee /etc/systemd/system/garage-webui.service >/dev/null <<'EOF'
[Unit]
Description=Garage Web UI
After=network-online.target nginx.service
Wants=network-online.target

[Service]
User=exedev
EnvironmentFile=/etc/garage-webui/env
ExecStart=/usr/local/bin/garage-webui
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now garage-webui

Put it behind your email#

nginx on port 8000, the VM's URL, sends visitors who aren't signed in to exe.dev's login and lets in only the emails in allowed-emails. The VM's nginx comes with a placeholder site on port 8000, so this removes it:

sudo tee /etc/nginx/sites-available/garage-webui >/dev/null <<'EOF'
# Garage Web UI behind exe.dev login. exe.dev's proxy sends X-ExeDev-Email
# for signed-in visitors; only emails in allowed-emails get through.
map $http_x_exedev_email $garage_webui_allowed {
    default 0;
    include /home/exedev/garage-webui/allowed-emails;
}
server {
    listen 8000;
    listen [::]:8000;
    absolute_redirect off;
    client_max_body_size 0;
    location / {
        default_type text/plain;
        if ($http_x_exedev_email = "") {
            return 302 /__exe.dev/login?redirect=$request_uri;
        }
        if ($garage_webui_allowed = 0) {
            return 403 "$http_x_exedev_email isn't in ~/garage-webui/allowed-emails on this VM.\n";
        }
        proxy_pass http://127.0.0.1:3909;
        proxy_set_header Host $host;
        proxy_read_timeout 300s;
    }
}
EOF
sudo ln -sf ../sites-available/garage-webui /etc/nginx/sites-enabled/garage-webui
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t && sudo systemctl reload nginx

Check the three cases: no email (sent to exe.dev login), someone else (refused), and you, with the UI reaching Garage:

email=$(head -n 1 ~/garage-webui/allowed-emails | cut -d' ' -f1)
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8000/
curl -s -o /dev/null -w '%{http_code}\n' -H 'X-ExeDev-Email: someone@example.com' http://localhost:8000/
curl -s -H "X-ExeDev-Email: $email" http://localhost:8000/api/v2/GetClusterHealth | jq -r .status
curl -s -H "X-ExeDev-Email: $email" http://localhost:8000/api/buckets | jq -r '.[].globalAliases[]'
curl -s -H "X-ExeDev-Email: $email" http://localhost:8000/api/browse/app-data | jq -r '.objects[].objectKey'

Expect 302, 403, healthy, your bucket names, and the files at the top of app-data (the last one reads over S3).

Update the UI

Check the releases for a newer version and what it changes, then swap the binary:

VERSION=1.1.0   # the new version
sudo curl -fsSL -o /usr/local/bin/garage-webui \
  "https://github.com/khairul169/garage-webui/releases/download/$VERSION/garage-webui-v$VERSION-linux-$(dpkg --print-architecture)"
sudo systemctl restart garage-webui

The UI keeps nothing on disk, so there's nothing to back up or migrate. When you update Garage to a new major version, check that the UI still supports its admin API (1.1 speaks Garage's v2 API; we tested Garage 2.5).

Something not working?

On this VM, journalctl -u garage-webui -n 50 and sudo tail -n 20 /var/log/nginx/error.log usually say what's wrong.

  • Pages load but show errors or no data: run the GetClusterHealth check in "Point it at Garage". integration not found or not attached to this VM means the garage-admin integration is missing or attached to another VM (ssh exe.dev integrations list on your computer); Forbidden: Invalid bearer token means the Garage admin token expired, was deleted, or lacks a scope: renew it.
  • Buckets list, but browsing fails: run the last check in "Point it at Garage". If it fails, check the garage-s3 integration the same way, and that the Garage page's nginx runs on port 8000 there. If it passes, check that the bucket has a key.
  • upstream SSL certificate verify error in nginx's log: keep proxy_ssl_verify_depth 4; exe.dev's certificate chain is longer than nginx's default allows.
  • 403 with your own email: the email in allowed-emails must match your exe.dev login exactly, followed by 1;.
  • After changing /etc/garage-webui/env nothing changed: restart the UI with sudo systemctl restart garage-webui; it reads its settings at start.

Frequently asked questions#

Why a separate VM instead of running it next to Garage?

Three reasons. You can share this VM with a teammate who needs the files without giving them the storage VM. The UI never reads Garage's config file: when it does, it sends the whole file, RPC secret and admin token included, to every browser that opens it. And it holds no secrets at all: its narrow admin token lives in an exe.dev integration, so not even someone with a shell here can read it.

Is garage-webui part of Garage?

No. Garage has no web UI of its own; garage-webui is a community project under the MIT license. Everything it does, the garage command can do too.

Can I change the cluster layout from the UI?

Not with the token this page makes. It leaves out layout changes and connecting nodes, which are rare and easy to get wrong. Use garage layout on the Garage VM, or give the UI a token with more scopes.

Does it work with a Garage cluster?

Yes. Point it at any one node; buckets, keys, and files are cluster-wide. We tested it with one node.

How big a file can I upload through the UI?

It sends each file in one request, not in parts. We uploaded 50 MB without trouble. For big files and whole folders, use rclone or aws s3 sync against Garage directly.

Is it free?

Yes, garage-webui and Garage are free and open source. You pay for the VMs; see exe.dev plans.

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