Skip to main content

Secret Management

API keys and tokens belong in the environment variable file only. The configuration file (settings.json) is plain text, so if the file leaks, the keys are exposed as-is.

This principle applies from the 2026.07 release onward; existing installations continue to work unchanged (see "Migrating Existing Installations" below).

There is exactly one source of truth: /etc/kopens/plantpulse-studio.env

The path of the environment variable file is /etc/kopens/plantpulse-studio.env. It sits outside the repo tree, not inside the installation directory (/opt/kopens/plantpulse-studio-docker), and its permissions are 0600. All three products — platform · ai · studio — use /etc/kopens/plantpulse-<product>.env under the same convention.

The .env at the root of the installation directory is the old path. Nothing reads it now, so editing it changes nothing in the stack. If the old file is still around, it is only good for cross-checking after migration.

The Six Secrets — What and When​

These are the values you put in .env. Leave the keys for features you don't use empty.

Environment VariablePurposeWhen It's NeededIf Missing
PLATFORM_API_KEYPlantPulse platform service keyAll live data queries (sites, equipment, tags, alarms)Live data cannot be queried from chat queries or deployed apps
ANTHROPIC_API_KEYAnthropic keyWhen the AI provider is anthropicThe agent does not actually run (stub responses)
OPENAI_API_KEYOpenAI keyWhen the AI provider is openaiSame as above
AI_API_KEYOpenAI-compatible gateway keyWhen using an in-house AI gatewaySame as above
GIT_TOKENRemote Git access token (PAT)When pushing app source to the customer's GitLab/GitHubOnly the Git push feature is unavailable
APP_REGISTRY_TOKENApp image registry tokenWhen pushing a deployed app as a Docker imageOnly the image push feature is unavailable
Only one of the three AI keys

You only need the single key matching the provider selected under Settings → AI tab. For sites using an in-house gateway (OpenAI-compatible), that is AI_API_KEY.

Entering Keys​

sudo vi /etc/kopens/plantpulse-studio.env
# ── 비밀(키·토큰) — 환경변수 전용 ─────────────────────────
PLATFORM_API_KEY=...
ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY=
# AI_API_KEY=
# GIT_TOKEN=
# APP_REGISTRY_TOKEN=
sudo chmod 600 /etc/kopens/plantpulse-studio.env
cd /opt/kopens/plantpulse-studio-docker && bash bin/restart.sh
docker restart will not change the keys

docker restart pp-studio-server does not re-read .env. It simply restarts carrying the old environment variables that were injected when the container was created. This is the classic trap where you change a key and then spend a long time wondering "why is it still the same?"

You must recreate the container.

bash bin/restart.sh
# 또는
docker compose up -d --force-recreate
Putting it in .env does not mean it reaches the container

Only the variables listed in the environment: section of docker-compose.yml are passed to the container. The six above are already wired up, but if you add a new variable that isn't in the table, you must add it to compose as well. (There are real cases where AI came up disabled because of a missed pass-through.)

Verifying It Took Effect​

# 서버가 인식한 키 출처 확인 — 부팅 로그
docker logs pp-studio-server 2>&1 | head -40

On screen, it's working correctly when the key input fields under the Settings → AI / Platform tabs are disabled and show "Managed by environment variable".

Precedence and Migrating Existing Installations​

RankSourceNotes
1Environment variable (/etc/kopens/plantpulse-studio.env)If a value is present, this always wins
2settings.jsonLegacy fallback — for compatibility with older installations

Upgrading will not suddenly break an existing installation. However, if secrets remain in the file, the boot log tells you what needs to move (values never appear in the log — only which item should move to which environment variable).

settings.json 에 비밀이 남아 있습니다 — … platform.apiKey → PLATFORM_API_KEY

Migration is a three-step procedure.

  1. Move the value to the corresponding environment variable in /etc/kopens/plantpulse-studio.env
  2. bash bin/restart.sh
  3. Confirm on the Settings screen that the item now reads "Managed by environment variable", then delete the old value from settings.json → the boot warning disappears
settings.json location

<DATA_ROOT>/state/settings.json (default /var/lib/pp-studio/state/settings.json). Back it up before editing, and restart after editing.

Key Rotation​

ANTHROPIC_API_KEY · AI_API_KEY have dedicated tooling. It updates the file and recreates the container in one step, and the value is not left in shell history.

cd /opt/kopens/plantpulse-studio-docker
bash bin/backup.sh                    # ① 되돌릴 지점 확보
bin/passwd.sh ANTHROPIC_API_KEY       # ② 값 생략 → 프롬프트로 입력
bash bin/status.sh                    # ③ 헬스 확인

Detailed usage is in Changing Passwords · API Keys.

The remaining keys (PLATFORM_API_KEY · OPENAI_API_KEY · GIT_TOKEN · APP_REGISTRY_TOKEN) are not covered by the tool; edit the file directly.

cd /opt/kopens/plantpulse-studio-docker
bash bin/backup.sh                              # ① 되돌릴 지점 확보
sudo vi /etc/kopens/plantpulse-studio.env       # ② 새 키로 교체
bash bin/restart.sh                             # ③ 컨테이너 재생성
bash bin/status.sh                              # ④ 헬스 확인

After rotation, the sure way to check real behavior is one chat query (verifies the platform key) and one app build (verifies the AI key).

Protections Applied Automatically​

ItemBehavior
File permissionsOn every server boot, settings.json · the environment variable file are forced to 0600 and the state directory to 0700
Audit logSettings changes record the fields that changed — for secrets, only a fingerprint (first 8 characters of the hash) instead of the value
UIKeys managed by environment variables have input disabled, so they cannot be overwritten by mistake
Key proxyingThe platform key stays inside the server and is attached only to requests from logged-in users (never to anonymous requests)

Exception — MCP External Server Tokens​

Tokens for external MCP servers, which users add in any number under Settings → MCP tab, cannot be expressed as environment variables because their count varies, so they are stored in settings.json. (These are less sensitive than the platform and AI keys.)

Rules to Follow​

What not to do
  • Do not commit the environment variable file or settings.json to version control (Git). This is exactly why the source of truth lives outside the repo tree (/etc/kopens/).
  • Do not paste keys into chat, email, or ticket bodies.
  • Do not share backup archives without authorization — see the handling cautions in Backup and Restore.
If you suspect exposure

Revoke first at the issuer (platform · AI provider · Git · registry), issue a new key, then perform the "Key Rotation" procedure above. The old key remains in memory until the server is restarted.