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. The [entrypoint] summary: block at the very end of the startup log tells you this at a glance via giip agent: on|off (reason) (giip #2855).

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.

🧩 How to Add New Target Servers (Install Docker → Appear as a Candidate)

The Provision now dropdown lists candidates per server (lssn), not per csn, and only servers that belong to the csn the instance was created for appear. To add targets, prepare a PC/server in the order below.

Step	What to do	How to verify
①	Install Docker on the target PC/server	docker version prints both Client and Server versions
②	Install and register the GIIP agent (belonging to the instance csn)	In lsvrdetail, check the lssn's csn and last check-in
③	Confirm docker_usage is reported	In kvslist, the latest row for kKey=<lssn>, kFactor=docker_usage has "dockerInstalled":true
④	Confirm it appears as a candidate	After Create, the server shows up in the dropdown
⑤	Run [Provision now]	See Method ② (Remote Provision now)

Installing Docker by OS

OS	What to install	How
Windows	Docker Desktop	Install from the official page https://docs.docker.com/desktop/setup/install/windows-install/ or use winget install -e --id Docker.DockerDesktop. Requires WSL 2 or Hyper-V (virtualization enabled).
macOS	Docker Desktop	Official page https://docs.docker.com/desktop/setup/install/mac-install/
Linux	Docker Engine	Follow the per-distribution steps in the official docs https://docs.docker.com/engine/install/ . After installing, add your user to the docker group (official "Linux post-installation steps"), log in again, and confirm docker version prints the server version.

The Docker daemon must be running after installation (for Docker Desktop, keep the app running).

⚠️ Currently Linux (Docker Engine) does not appear in the candidate list. We confirmed that giipAgentLinux (origin/main) has no code that collects or reports docker_usage; the only agent that reports it is the Windows agent (CollectDockerMetrics.ps1 in giipAgentWin). Installing Docker on a Linux server therefore does not make it a dropdown candidate; in that case start the container with Method ① (manual).

Candidate condition (Windows agent)

On every run the Windows agent checks that the docker CLI is on PATH and reports dockerInstalled=true when docker version --format '{{.Server.Version}}' returns a server version. If the CLI is missing or the daemon is stopped, it reports false.

Installing the GIIP agent

Follow the guides below instead of this document. The agent must belong to the csn the instance was created for.

• Windows agent setup guide
• Linux/WSL agent setup guide
• Agent CSN registration

🤖 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.

🤖 When You Give an AI Agent Only This Document's URL

Even if a user hands an AI agent only the URL of this document (https://giip.littleworld.net/en/guides/docker-instances; raw text at https://giip.littleworld.net/help/docker-instances.en.md), the AI can add a target server by following the order below.

What the user must provide: (1) the working csn (the csn the instance is created for), (2) how to reach the target PC/server (whether the AI runs commands on that PC directly, or connects remotely).

1. Start with read-only checks. Check the target PC's OS, Docker installation and daemon state (docker version), GIIP agent installation and run state, and the lssn in giipAgent.cfg (never print sk).
2. Install/configure only the missing steps. Do not touch steps ①-③ of "How to Add New Target Servers" that are already satisfied. Installing changes the user's PC, so tell the user what will be installed before running it.
3. Do not guess the csn. Check the lssn's csn in lsvrdetail and confirm it matches the csn the instance was created for.
4. Report only after confirming the candidate appears. Confirm "dockerInstalled":true in docker_usage in kvslist, and that the server shows up in the dropdown after creating the instance. If the server structurally cannot become a candidate (such as a Linux server), report that fact and Method ① (manual).

The rules the AI must follow are the same as "What an AI must not do" above (do not print sk or the instance token, do not use another csn's SK, do not guess).

💡 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
/work/giipAgentLinux has only log/ and looks like an "empty shell clone"	A trace of a boot that skipped the agent block (GIIP_SK unresolved or GIIP_ENABLE_AGENT=false). A proper clone has .git + 7 directories at the root, so ls -la's link count is 10; an observed count of 3 (. + .. + a single log/) means only the log directory was created, not a clone	In docker logs, confirm the cause via skipping giip agent and the giip agent: off (reason) line in the [entrypoint] summary: block (usually GIIP_SK unresolved / token fetch failure). Once you fix the cause and restart, the latest entrypoint moves the residue aside to .bak-<timestamp> and re-clones automatically (giip #2855). An older image (before this fix) requires you to manually delete that directory inside the volume to clear the not an empty directory rejection
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.3 Last updated: 2026-10-15 (added "How to Add New Target Servers" and "When You Give an AI Agent Only This Document's URL") Source file: giipv3/public/help/docker-instances.en.md