Docker Instance Management Guide

Docker instances let you deploy the GIIP agent as a container on a remote PC/server and manage it from the GIIP web interface. Once you provide the instance token to the target machine and start the container, that machine begins acting as a GIIP agent (polling every minute) and optionally as a slack-bot.

🏢 Go to Docker Instance Management →

📋 Overview

The Docker Instance Management page lets you create and manage Docker container instances for deploying the giip-fde-agent to remote machines. When you create an instance, GIIP server encrypts credentials with AES-256-GCM and issues a single-use bootstrap token.

⚠️ This page requires admin access. You must have uLevel >= 70 to access it. Users below this level are redirected to the home page.

🔍 Page Layout

1. Header

• Page title: "Docker Instance Management"
• + Create Docker instance button: Opens the creation modal.

2. Instance List Table

Column	Description
Label	Instance name (falls back to #<diSn> if not set)
LSSN	Pre-registered lsvr serial number. Shown in the token display area right after creation and in this list. Click to go to lsvrdetail
Created	Creation timestamp
Last fetched	Last time the container used the token to fetch env from GIIP. This is NOT real-time liveness — it's the last activation time.
Status	Active (green) or Revoked (red) badge. Rows where the CQE bootstrap may fail to run due to an ownership mismatch show a warning icon (⚠️) next to the badge — hover for details, click to open that lssn's run list (cqelsvrRunList) (giip 3062)
Actions	Revoke button — invalidates the token (does not stop a running container)

⚠️ When Last fetched is -: The container has never been started. You have not yet run Procedure ① (manual) or ② (Provision now).

🛠️ Creating an Instance

1. Click + Create Docker instance.
2. Fill in the 3 required fields:
   • GIIP_LOGIN_ID: Your GIIP login account (e.g., user@example.com)
   • GIIP_SK: Your GIIP secret key (different from password)
   • GIIP_CSN: Your CSN number (e.g., 47)
3. Optional fields:
   • Label: Instance name (e.g., lowy-dp01-docker)
   • GIIP_PROJECT_NAME: Defaults to docker
   • GIIP_WORKDIR: Working directory (optional)
   • GIIP_REST_BRANCH: Git branch (optional)
   • SLACK_BOT_TOKEN / SLACK_APP_TOKEN / SLACK_CHANNEL_ID: Slack bot (optional — requires both tokens)
   • Enable hourly-issue-scheduler: Checkbox (on by default) — runs the issue scheduler at :07 every hour
4. Click Create.

Copy the token immediately

After creation, the token is shown exactly once.

GIIP_INSTANCE_TOKEN=<token>

Closing the modal permanently hides the token. You need this token to start the container, so copy it before proceeding.

🛠️ Starting the Container After Creation — Method ① (Manual, all environments)

After copying the token, run the following on the target PC/server:

# 1. Clone the giip-fde-agent repo
git clone https://github.com/LowyShin/giip-fde-agent.git
cd giip-fde-agent/docker

# 2. Write only the token to .env
echo 'GIIP_INSTANCE_TOKEN=<copied token>' > .env

# 3. Start with Docker Compose
docker compose up -d --build

• Only the token is needed in .env. The fetch-instance-env.sh script fetches the remaining env vars from the dockerInstanceFetch API (using the token itself as credentials).
• If you add other keys directly in .env, those values take priority (partial override supported).

🛠️ Starting the Container After Creation — Method ② (Remote "Provision now")

Only available if the target PC already has a GIIP agent running with an existing lssn. (giip 3043) The dropdown only lists lssn values that have Docker Desktop installed and have reported usage at least once — the newly created instance's own lssn (whose agent has never checked in) never appears as a candidate.

1. On the token display screen, pick a target with spare resources from the dropdown (CPU/Mem/Disk usage and running container count are shown alongside each option). If no candidates are listed, a notice appears instead of the dropdown — in that case, use method ① (manual) below.
2. Click [Provision now].
3. A bootstrap script (mssn=6122) is queued and immediately force-executed (CQERunForce).

⚠️ This only works if GIIP agent is already installed on the target PC. If the agent is not present, use Method ① instead.

ℹ️ Permissions: [Provision now] is checked by the server (DockerInstanceProvision). Any member of the instance's csn and of the target server's csn can run it — you do not need to own the bootstrap script. If it fails, the reason is shown on the page (see the troubleshooting table below); the instance is already created and the token is still valid, so you can continue with manual procedure ①.

⚠️ Takes up to 1 minute: The GIIP agent on the target PC polls approximately every 60 seconds, so wait up to 1 minute for the container to start.

🔍 Verifying "Connection" After Creation — 3 Paths

There is no terminal inside GIIP web to connect to the container. Verification is done through these 3 methods.

1. Shell Access (on target PC)

docker exec -it giip-fde-agent bash

The container name is always giip-fde-agent.

2. Log Review (on target PC)

docker compose logs -f          # from the docker/ directory
docker logs -f giip-fde-agent   # from anywhere

If startup succeeded, you will see:

• [entrypoint] cloned ...
• [fetch-instance-env] env applied from GIIP_INSTANCE_TOKEN
• [entrypoint] registered giipAgentLinux cron (every 1 min)
• [entrypoint] ready. tailing logs.

3. GIIP Web Verification — lsvrlist (Server List)

This is the canonical "how to verify from GIIP web" method.

The lsvr is pre-registered at instance creation time — when you create an instance, the lssn is issued immediately and shown in the UI, so the lsvr appears in lsvrlist before the container even starts (giip 2856).

On container startup:

1. giipAgentLinux is cloned.
2. giipAgent.cnf (sk=registered GIIP_SK, lssn=GIIP_LSSN env value) is created.
3. giipAgent3.sh runs every minute (but since lssn is not 0, it maintains the existing lsvr instead of calling CQEQueueGet's self-registration path).
4. The container now appears in lsvrlist alongside other servers.

Verification path: /en/lsvrlist → find the relevant lssn → lsvrdetail → check tLSvr.lsChkdt heartbeat for liveness

⚠️ Without GIIP_SK or with GIIP_ENABLE_AGENT=false, this registration does not happen and you cannot see the container status in GIIP web.

4. Slack Verification (with Slack bot)

If you provided both SLACK_BOT_TOKEN and SLACK_APP_TOKEN, the slack-bot starts via pm2. If the bot responds in the configured channel, it is running correctly.

⚠️ If either token is missing, the bot is skipped entirely. Having only one token and seeing nothing is expected behavior.

🤖 Connection manual for AI agents (when the Provision now target is not listed)

Steps an AI agent follows to connect a PC as a Docker Instance target on behalf of a person. Every step is read-only; look values up, do not guess them.

What the message means

"No servers with Docker Desktop detected yet for this csn" is not an error — it means the candidate list is empty. A server is a candidate only when all three hold:

1. The server (lssn) belongs to the csn the instance was created in.
2. Its GIIP agent has reported docker_usage, and the latest value has "dockerInstalled":true.
3. The candidate-list API (DockerCapableLsvrList) is deployed on the server.

1. Find the target PC's lssn and csn

• Read lssn from the agent config giipAgent.cfg (never print the sk value). For the Windows agent, find the folder from the run path of the Task Scheduler job GIIP Agent Task (v3) and read giipAgent.cfg in its parent folder.
• Check that lssn's csn in the GIIP web lsvrdetail. It must equal the csn the instance was created in.

2. Check the agent and Docker

• Windows: Get-ScheduledTask 'GIIP Agent Task (v3)' | Get-ScheduledTaskInfo — LastTaskResult must be 0 (success) or 267009 (running).
• The agent log must contain [CollectDockerMetrics] ... Successfully collected and uploaded Docker resource usage on every run.
• Docker Desktop must be running: docker version must print the server version.

3. Check the reported Docker usage

Open the GIIP web kvslist with kKey=<lssn> and kFactor=docker_usage. The latest row must contain "dockerInstalled":true for the server to become a candidate. If it is missing or false, go back to step 2.

4. Everything is fine but the list is still empty (administrator)

The candidate-list API is not deployed. The same message used to appear in this case, hiding the cause; now the page shows the error "The candidate-list API returned an unexpected response". An administrator checks whether the stored procedure pApiDockerCapableLsvrListbyAK exists and, if not, deploys giipdb SP/pApiDockerCapableLsvrListbyAK.sql with mgmt/execSQLFile.ps1.

5. When there is no server to connect

• Without a GIIP agent on the target PC, [Provision now] cannot be used. Install and register the agent first, or use manual procedure ①.
• An lssn whose agent has never connected (empty last check-in) is not a candidate. The lssn that is pre-registered when an instance is created is such a case — do not pick it as a target.

What an AI must not do

• Do not print or record sk, the instance token, or a token inside a queued script body.
• Do not query or write with another csn's SK (check the csn first).
• Do not guess values; report only what the lookups above show.

💡 Notes

• Last fetched ≠ real-time liveness: Last fetched shows "when the container last pulled env from GIIP." If the container is stopped, this value remains unchanged. For real-time status, check the lsvrlist heartbeat.
• Revoke does not delete the row: Revoke only invalidates the token; the row remains as an audit trail with a Revoked badge.
• Revoke does not stop a running container. You must run docker compose down on the target PC to stop it.
• Container name: Manual procedure ① and existing instances use giip-fde-agent. [Provision now] starts each instance as giip-fde-agent-<diSn> (compose project giip-fde-<diSn>), so several instances can run on one PC. Find the diSn in the diSn column of the list table.

Troubleshooting

Symptom	Cause	Solution
"No servers with Docker Desktop detected yet for this csn" appears	(a) The agent on the target PC is not running or Docker Desktop is off, so there is no docker_usage (b) The server's csn differs from the instance's csn (c) The candidate-list API is not deployed on the server	Check steps 1–4 of the "Connection manual for AI agents" below. To proceed right away, use manual procedure ①.
Did not copy the token	Cannot be retrieved	Revoke the existing instance and create a new one.
docker compose up succeeded but nothing in lsvrlist	(a) GIIP_ENABLE_AGENT=false (b) GIIP_SK empty (c) first poll not yet due (d) 401 auth error	Check /work/giipAgentLinux/log/cron.log in docker logs for 401 errors
New lssn assigned on every restart	/work volume is ephemeral	Verify docker-compose.yml volume maps to giip-fde-agent-data:/work (entire /work persisted)
[Provision now] fails	Reason shown on the page: Forbidden: not a member of the instance csn / ...target server csn (you are not a member of that csn), Target server has not reported Docker Desktop (the target never reported Docker — check the agent and Docker Desktop), still pending (a previous request is waiting — retry in about 5 minutes), Docker instance is revoked / not found	Act on the reason shown. To proceed right away use manual procedure ① (docker compose up). The token is still valid.
[Provision now] shows a success message but lsvrlist and the container show no change after several minutes	(a) The agent on the target lssn is dead, so it never polls in the first place (b) This schedule alone was isolated as undeliverable (BLOCKED) (giip #2557-type)	(a) Check the target lssn's last check-in time in lsvrdetail — if it's stale, inspect the agent/network on the target PC first (b) Ask an admin to check for undeliverable schedules for that lssn/csn. If it still hasn't run after a few minutes, fall back to Method ① (manual)
Slack bot not starting	Both SLACK_BOT_TOKEN and SLACK_APP_TOKEN are required	Having only one causes the bot to be skipped entirely.
Immediately redirected to home	uLevel below 70	Log in with an admin account (level 70+).

---

Version: 1.2 Last updated: 2026-09-25 (documented the CQE ownership-mismatch warning icon next to the Status badge, giip 3062) Source file: giipv3/public/help/docker-instances.en.md