diff --git a/skills/build-agent/SKILL.md b/skills/build-agent/SKILL.md
index 54c1da6..8872080 100644
--- a/skills/build-agent/SKILL.md
+++ b/skills/build-agent/SKILL.md
@@ -28,19 +28,30 @@ fallback; prefer what is written here.
 
 Do these two things once, before any build.
 
-**1. Credentials.** The scripts need `AGENTA_API_KEY`, and `AGENTA_HOST` only if the user
-self-hosts (it defaults to Agenta cloud, `https://cloud.agenta.ai`).
+**1. Credentials.** The scripts need `AGENTA_API_KEY`, and `AGENTA_API_URL` only if the user
+self-hosts or is on a non-default cloud region (it defaults to `https://cloud.agenta.ai/api`).
+
+`AGENTA_API_URL` is the full API URL, already including `/api` (e.g.
+`https://eu.cloud.agenta.ai/api`, or `http://localhost/api` for a local self-hosted install)
+— this matches how the Agenta SDK itself resolves the backend.
 
 - Ask the user for their API key. Point them to it: the **API keys** page in their Agenta
-  project settings (on cloud, under `https://cloud.agenta.ai`). Ask for the host URL only if
-  they self-host, in which case it is their own Agenta domain.
+  project settings (on cloud, under `https://cloud.agenta.ai`). Ask for the API URL only if
+  they self-host or use a non-default cloud region, in which case it is their own Agenta
+  domain plus `/api`.
 - Then offer to set it up for them, either way they prefer:
   - **Write it for them:** create a `.env` file in the working directory with
-    `AGENTA_API_KEY=...` (and `AGENTA_HOST=...` if self-hosting). `lib.sh` picks up a local
-    `.env` automatically.
+    `AGENTA_API_KEY=...` (and `AGENTA_API_URL=https://your-domain/api` if self-hosting).
+    `lib.sh` picks up a local `.env` automatically.
   - **Hand them a block to paste:** give them the lines to `export`, or the `.env` contents
     to create themselves.
 - Never print or commit the key. Add `.env` to `.gitignore` if the directory is a repo.
+- **`https://cloud.agenta.ai` above is a one-time example for INITIAL setup only.** If a
+  later runtime error tells you to add a credential to the project vault (or anything else
+  that means "go to your Agenta project"), point the user at their actual configured API
+  host — read it from `AGENTA_API_URL`/`.env`, don't repeat the cloud URL from this section
+  by habit. A self-hosted user sent to `cloud.agenta.ai` for a vault that lives on their own
+  domain will not find what you told them to look for.
 
 **2. Prerequisites.** Run `bash scripts/check-prereqs.sh`. It verifies `bash`, `curl`, and
 `jq` are installed. On a miss it prints the exact install command for the user's platform;
@@ -180,6 +191,12 @@ Keep to the loop above for a simple agent. Read one of these only when the task
 - **Crons are UTC, five fields, one-minute floor.** Convert the user's local time yourself.
 - **needs_auth means stop.** If a needed connection is not `ready`, stop and ask the user to
   connect it. That is the whole job for that step.
+- **Remediation guidance always uses the user's actual configured API host, never a
+  hardcoded cloud URL.** The `https://cloud.agenta.ai` example in the credentials section
+  above is for *initial* setup only. If a later runtime failure calls for telling the user to
+  go add something in their Agenta project (a vault key, a setting), point them at their
+  actual `AGENTA_API_URL` — a self-hosted user
+  sent to the cloud URL will look in the wrong place.
 - **Discovery is a search, not an oracle.** `discover-tools.sh` / `discover-triggers.sh` return
   high-recall best guesses over the live catalog. The matched **connection state** is reliable;
   the matched **integration and action** are not always right. A search matches on words: "save
diff --git a/skills/build-agent/scripts/lib.sh b/skills/build-agent/scripts/lib.sh
index 71f4e57..b2a8a82 100755
--- a/skills/build-agent/scripts/lib.sh
+++ b/skills/build-agent/scripts/lib.sh
@@ -5,7 +5,9 @@
 #
 # Credentials (set by you before running any script):
 #   AGENTA_API_KEY   required. From your Agenta project settings (API keys).
-#   AGENTA_HOST      optional. Defaults to Agenta cloud. Set it only if self-hosting.
+#   AGENTA_API_URL   optional. The full API URL, e.g. https://eu.cloud.agenta.ai/api or
+#                    http://localhost/api. Set it if self-hosting or on a non-default cloud
+#                    region. Defaults to https://cloud.agenta.ai/api.
 #
 # Precedence: values already in the environment win. If AGENTA_API_KEY is not in the
 # environment, the kit falls back to a .env file (AGENTA_ENV_FILE, then ./.env, then a
@@ -24,14 +26,18 @@ if [ -z "${AGENTA_API_KEY:-}" ]; then
   done
 fi
 
-# Cloud is the default. Self-hosted users set AGENTA_HOST to their own domain.
-: "${AGENTA_HOST:=https://cloud.agenta.ai}"
+# Cloud is the default. AGENTA_API_URL already includes /api (e.g. https://eu.cloud.agenta.ai/api).
+: "${AGENTA_API_URL:=https://cloud.agenta.ai/api}"
+_API_BASE="${AGENTA_API_URL%/}"
+# Every call site below builds its own /api/... or /services/... path, so also keep a bare
+# root (no /api suffix) for the one call site that needs a non-/api path.
+_API_ROOT="${_API_BASE%/api}"
 
 if [ -z "${AGENTA_API_KEY:-}" ]; then
   {
     echo "AGENTA_API_KEY is not set."
     echo "Get a key from your Agenta project settings (API keys page), then set it one of two ways:"
-    echo "  export AGENTA_API_KEY=...        # and AGENTA_HOST=https://your-domain if self-hosting"
+    echo "  export AGENTA_API_KEY=...        # and AGENTA_API_URL=https://your-domain/api if self-hosting"
     echo "  echo 'AGENTA_API_KEY=...' > .env # a .env in this directory is picked up automatically"
   } >&2
   exit 1
@@ -39,9 +45,9 @@ fi
 
 _AUTH=(-H "Authorization: ApiKey $AGENTA_API_KEY" -H "Content-Type: application/json")
 
-agenta_post()   { curl -s -X POST   "$AGENTA_HOST$1" "${_AUTH[@]}" -d "$2"; }
-agenta_get()    { curl -s           "$AGENTA_HOST$1" "${_AUTH[@]}"; }
-agenta_delete() { curl -s -X DELETE "$AGENTA_HOST$1" "${_AUTH[@]}"; }
+agenta_post()   { curl -s -X POST   "$_API_ROOT$1" "${_AUTH[@]}" -d "$2"; }
+agenta_get()    { curl -s           "$_API_ROOT$1" "${_AUTH[@]}"; }
+agenta_delete() { curl -s -X DELETE "$_API_ROOT$1" "${_AUTH[@]}"; }
 
 # Resolves a <revision_id> argument for create-schedule.sh / create-subscription.sh.
 # A real revision id (from create-agent.sh / build.sh / update-agent.sh) passes straight
diff --git a/skills/build-agent/scripts/test-agent.sh b/skills/build-agent/scripts/test-agent.sh
index 3ad203f..0098863 100755
--- a/skills/build-agent/scripts/test-agent.sh
+++ b/skills/build-agent/scripts/test-agent.sh
@@ -53,7 +53,7 @@ RESP_FILE="$TMP/resp.json"; HDR="$TMP/headers"
 
 # Accept: application/json negotiates the non-streaming (batch) invoke — one JSON object back,
 # not an event stream.
-curl -s -X POST "$AGENTA_HOST/services/agent/v0/invoke" \
+curl -s -X POST "$_API_ROOT/services/agent/v0/invoke" \
   -H "Authorization: ApiKey $AGENTA_API_KEY" -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   --max-time 600 -D "$HDR" -d "$BODY" > "$RESP_FILE"