Module: VIBE

• 1: Configuration
• 2: Parameters
• 3: Playbook
• 4: Administration
• 5: Monitoring
• 6: FAQ

./configure -c vibe
./deploy.yml --check          # preview NODE, INFRA, ETCD, MINIO, and PGSQL targets
./deploy.yml                  # deploy after confirming the target set
./juice.yml -l <host> --check # optional shared storage preview
./juice.yml -l <host>         # deploy shared storage after review
./vibe.yml -l <host> --check  # preview VIBE changes
./vibe.yml -l <host>          # deploy VIBE after review

1 - Configuration

VIBE supports enabling components on demand and exposes services via a unified workspace and Nginx portal.

Overview

Note: module default is jupyter_enabled: false, while conf/vibe.yml explicitly sets it to true.

Config usually lives in cluster vars, and can be overridden at instance level:

all:
  children:
    infra:
      hosts:
        10.10.10.10:
          vibe_data: /fs
          code_enabled: true
          jupyter_enabled: true
          claude_enabled: true
          codex_enabled: true

Workspace

vibe_data is the unified workspace for VIBE:

• Code-Server default open directory
• JupyterLab root_dir
• Claude Code working dir
• Render the AGENTS.md context file and create a CLAUDE.md symlink to it

The vibe_dir task creates the directory and context files, owned by node_user.

vibe_data: /fs

Code-Server

code_enabled: true
code_port: 8443
code_data: /data/code
code_password: Vibe.Coding
code_gallery: openvsx

Notes:

• Service listens on 127.0.0.1:<code_port> (default 8443), accessed via Nginx /code/
• Config file: code_data/code-server/config.yaml (default /data/code/code-server/config.yaml)
• Env file: /etc/default/code, used to configure extension marketplace

Extension marketplace:

• code_gallery: microsoft uses Microsoft marketplace
• When region=china, Open VSX defaults to Tsinghua mirror

JupyterLab

jupyter_enabled: true
jupyter_port: 8888
jupyter_data: /data/jupyter
jupyter_password: Vibe.Coding
jupyter_venv: /data/venv

Notes:

• Service listens on 0.0.0.0:<jupyter_port> (default 8888), base path /jupyter/
• Config file: jupyter_data/jupyter_config.py (default /data/jupyter/jupyter_config.py)
• Login token: c.IdentityProvider.token
• The v4.5 template also sets allow_origin = '*', disable_check_xsrf = True, and trust_xheaders = True; these relax the security boundary for a reverse-proxied development sandbox
• Venv is not created automatically, use node_uv_env in NODE module beforehand

Use a high-entropy random token and restrict TCP/8888 to trusted networks or the reverse proxy. infra_portal.home does not enable Basic Auth by default. For a second authentication layer, configure nginx_users and set auth: true on the portal. If you tighten the Jupyter settings, validate WebSockets, origin handling, and login before rollout.

Create venv example:

uv venv /data/venv

Node.js

nodejs_enabled: true
nodejs_registry: ''
npm_packages: []

Notes:

• When nodejs_registry is empty and region=china, default registry is https://registry.npmmirror.com
• npm_packages installs additional global npm packages and is empty by default
• Claude Code and Codex CLI are installed by their own dedicated tasks

Claude Code

The claude task installs the CLI (claude_install) and writes its configuration (claude_config).

claude_enabled: true
claude_package: '@anthropic-ai/claude-code'
claude_env:
  ANTHROPIC_API_KEY: sk-ant-xxx

When Claude or Codex is enabled, VIBE ensures that the Node.js runtime is installed. Override claude_package to use a different Claude npm package.

Generated files:

• ~/.claude.json
• ~/.claude/settings.json

claude_env is merged with default OpenTelemetry env vars, sending telemetry to VictoriaMetrics / VictoriaLogs.

Codex CLI

codex_enabled: true

The codex task runs npm install -g @openai/codex. VIBE installs Codex CLI only; it does not write Codex configuration or connect it to VIBE’s Claude Code observability.

Nginx Portal

VIBE exposes services through infra_portal. By default, home domain includes /code/ and /jupyter/ paths.

For dedicated domains:

infra_portal:
  code: { domain: code.pigsty, endpoint: "127.0.0.1:8443", websocket: true, auth: true }
  jupyter: { domain: jupyter.pigsty, endpoint: "127.0.0.1:8888", websocket: true, auth: true }
nginx_users:
  devadmin: '<strong-password>'

2 - Parameters

VIBE module has 18 parameters, grouped as:

• Common
• Code-Server
• JupyterLab
• Node.js
• Claude Code
• Codex CLI

Overview

Default Parameters

Defined in roles/vibe/defaults/main.yml:

vibe_data: /fs

code_enabled: true
code_port: 8443
code_data: /data/code
code_password: Vibe.Coding
code_gallery: 'openvsx'

jupyter_enabled: false
jupyter_port: 8888
jupyter_data: /data/jupyter
jupyter_password: Vibe.Coding
jupyter_venv: /data/venv

nodejs_enabled: true
nodejs_registry: ''
npm_packages: []

claude_enabled: true
claude_package: '@anthropic-ai/claude-code'
claude_env: {}

codex_enabled: true

Common

vibe_data

Workspace directory, default /fs. Code-Server and JupyterLab use it as their workspace root; vibe_dir renders AGENTS.md here and creates a CLAUDE.md symlink to it.

Code-Server

code_enabled

Enable Code-Server, default true.

code_port

Listen port, default 8443; bound to 127.0.0.1 and forwarded by Nginx /code/.

code_data

Data dir, config file at code_data/code-server/config.yaml (default /data/code/code-server/config.yaml).

code_password

Login password, default Vibe.Coding; it must be changed in production.

code_gallery

Extension marketplace: openvsx / microsoft. When region=china and openvsx, Tsinghua mirror is used.

JupyterLab

jupyter_enabled

Enable JupyterLab. Module default is false; conf/vibe.yml explicitly sets it to true to enable a full sandbox.

jupyter_port

Listen port, default 0.0.0.0:8888.

jupyter_data

Data dir, config file at jupyter_data/jupyter_config.py (default /data/jupyter/jupyter_config.py).

jupyter_password

Access token, default Vibe.Coding, written to c.IdentityProvider.token.

jupyter_venv

Python venv path for JupyterLab, default /data/venv; it must be created beforehand (usually by the NODE module).

Node.js

nodejs_enabled

Enable the standalone Node.js installation task, default true.

nodejs_registry

npm registry mirror; when empty and region=china, defaults to https://registry.npmmirror.com.

npm_packages

Additional global npm packages, tagged nodejs_pkg; empty by default. Claude Code and Codex CLI are installed by their own dedicated tasks and do not need to be added here.

Claude Code

claude_enabled

Enable Claude Code installation and configuration, default true. claude_install installs the CLI, while claude_config writes its configuration.

claude_package

The npm package used for Claude Code; defaults to @anthropic-ai/claude-code.

claude_env

Extra env vars merged into default OpenTelemetry config.

Default env vars include:

• CLAUDE_CODE_ENABLE_TELEMETRY=1
• OTEL_METRICS_EXPORTER=otlp
• OTEL_LOGS_EXPORTER=otlp
• OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
• OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=http/protobuf
• OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://127.0.0.1:8428/opentelemetry/v1/metrics
• OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://127.0.0.1:9428/insert/opentelemetry/v1/logs
• OTEL_RESOURCE_ATTRIBUTES=ip=<inventory_hostname>,job=claude

Codex CLI

codex_enabled

Whether to install Codex CLI; defaults to true. When enabled, codex_install runs npm install -g @openai/codex. VIBE installs Codex CLI only; it does not manage Codex configuration or configure OpenTelemetry for it.

3 - Playbook

VIBE provides the vibe.yml playbook to deploy Code-Server, JupyterLab, Node.js, Claude Code, and Codex CLI.

vibe.yml includes only node_id and vibe roles, it does not include node/infra. Run deploy.yml first, or explicitly run node.yml and infra.yml.

vibe.yml

vibe.yml:

- name: VIBE
  hosts: all
  become: true
  gather_facts: no
  roles:
    - { role: node_id, tags: id }
    - { role: vibe,    tags: vibe }

Task Structure

vibe
├── vibe_dir          # create workspace and context files
├── code              # Code-Server
│   ├── code_install
│   ├── code_dir
│   ├── code_config
│   └── code_launch
├── jupyter           # JupyterLab
│   ├── jupyter_install
│   ├── jupyter_dir
│   ├── jupyter_config
│   └── jupyter_launch
├── nodejs            # Node.js runtime and additional npm packages
│   ├── nodejs_install
│   ├── nodejs_config
│   └── nodejs_pkg
├── codex             # Codex CLI
│   └── codex_install
└── claude            # Claude Code
    ├── claude_install
    └── claude_config

Notes:

• jupyter_install uses uv pip, it does not create venv
• nodejs_pkg installs only the additional packages declared in npm_packages; the list is empty by default
• claude_install installs Claude CLI with claude_package, while claude_config writes the ~/.claude configuration
• codex_install installs @openai/codex and does not manage Codex configuration

Common Commands

Full deploy:

./vibe.yml -l <host> --check   # Preview first
./vibe.yml -l <host>           # Apply after confirming the target

Component-level:

./vibe.yml -l <host> -t code
./vibe.yml -l <host> -t jupyter
./vibe.yml -l <host> -t nodejs
./vibe.yml -l <host> -t claude
./vibe.yml -l <host> -t codex

Config updates:

./vibe.yml -l <host> -t code_config,code_launch
./vibe.yml -l <host> -t jupyter_config
ssh <host> sudo systemctl restart jupyter
./vibe.yml -l <host> -t claude_config

Skip components for this run:

./vibe.yml -l <host> -e code_enabled=false
./vibe.yml -l <host> -e jupyter_enabled=false
./vibe.yml -l <host> -e nodejs_enabled=false
./vibe.yml -l <host> -e claude_enabled=false
./vibe.yml -l <host> -e codex_enabled=false

These switches are task conditions. Setting one to false only skips the corresponding installation and configuration tasks; it does not stop, disable, or uninstall a service or package deployed earlier. To retire Code-Server or JupyterLab, run systemctl disable --now code-server or systemctl disable --now jupyter separately. VIBE currently has no dedicated removal playbook.

Node.js is a runtime dependency of Claude Code and Codex CLI. If nodejs_enabled=false but either claude_enabled or codex_enabled remains true, the nodejs phase still runs. It is skipped only when all three switches are false.

Deployment Order

./deploy.yml --check          # Preview inventory-defined base components
./deploy.yml                  # Deploy after review
./juice.yml -l <host> --check # Optional shared-storage preview
./juice.yml -l <host>
./vibe.yml -l <host> --check  # VIBE preview
./vibe.yml -l <host>

Idempotency

vibe.yml is idempotent. Re-run after config changes.

4 - Administration

Service Management

systemctl status code-server
systemctl restart code-server
systemctl status jupyter
systemctl restart jupyter

Logs:

journalctl -u code-server -f
journalctl -u jupyter -f

Workspace and Context

vibe_dir creates these under vibe_data:

• AGENTS.md: Context file rendered from the role template
• CLAUDE.md: Symlink to AGENTS.md

Default locations (adjustable via vibe_data):

/fs/CLAUDE.md
/fs/AGENTS.md

Password and Auth

Code-Server

Edit config:

vi /data/code/code-server/config.yaml
systemctl restart code-server

Or via Ansible:

# Persist the new password in inventory first so it does not enter shell history
./vibe.yml -l <host> -t code_config,code_launch --check
./vibe.yml -l <host> -t code_config,code_launch

JupyterLab

Config file: /data/jupyter/jupyter_config.py

Field: c.IdentityProvider.token

The current v4.5 template also allows any Origin and disables XSRF checks, so the token is its primary authentication barrier. Use a strong random token, restrict TCP/8888, and access it through a trusted TLS reverse proxy. Persist a new token in inventory, then preview and apply it:

./vibe.yml -l <host> -t jupyter_config --check
./vibe.yml -l <host> -t jupyter_config
ssh <host> sudo systemctl restart jupyter

Code-Server Extensions

code-server --install-extension ms-python.python
code-server --list-extensions
code-server --uninstall-extension ms-python.python

Switch extension marketplace:

code_gallery: microsoft

Redeploy:

./vibe.yml -l <host> -t code_config,code_launch

JupyterLab Environment

VIBE does not create venv automatically, ensure jupyter_venv exists:

uv venv /data/venv

Install/upgrade JupyterLab:

uv pip install --python /data/venv/bin/python jupyterlab ipykernel
systemctl restart jupyter

Install extensions (in venv):

source /data/venv/bin/activate
pip install jupyterlab-git
systemctl restart jupyter

Claude Code

The claude_install subtask installs Claude CLI, while claude_config writes the configuration files.

which claude
claude --version

Config files:

• ~/.claude.json
• ~/.claude/settings.json

Update config:

./vibe.yml -l <host> -t claude_config

Reinstall/install Claude CLI:

./vibe.yml -l <host> -t claude_install
# or install manually
npm install -g @anthropic-ai/claude-code

Override claude_package if you need a different npm package.

Codex CLI

VIBE installs @openai/codex through codex_install, but does not manage Codex configuration:

which codex
codex --version
./vibe.yml -l <host> -t codex_install

To configure for another user, run as that user or copy the files manually.

File Locations

Troubleshooting

Port checks:

ss -tlnp | grep 8443
ss -tlnp | grep 8888

Nginx entry:

nginx -t
systemctl status nginx

5 - Monitoring

VIBE monitoring mainly focuses on Claude Code OpenTelemetry data. Code-Server and JupyterLab do not expose Prometheus metrics; use systemd and logs for health checks.

Claude Code Observability

VIBE writes default OpenTelemetry env vars into ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_METRICS_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_LOGS_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT": "http://127.0.0.1:8428/opentelemetry/v1/metrics",
    "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": "http://127.0.0.1:9428/insert/opentelemetry/v1/logs",
    "OTEL_RESOURCE_ATTRIBUTES": "ip=<host>,job=claude"
  }
}

claude_env is merged with the defaults, and can be used for API keys or custom endpoints.

Grafana Dashboard

Grafana includes claude-code dashboard by default:

• Portal: https://<domain>/ui/d/claude-code
• Direct: http://<ip>:3000/d/claude-code

Runtime Checks

systemctl status code-server
systemctl status jupyter
journalctl -u code-server -f
journalctl -u jupyter -f

Port checks:

ss -tlnp | grep 8443
ss -tlnp | grep 8888

Claude Logs Query

Via VictoriaLogs:

curl -G 'http://127.0.0.1:9428/select/logsql/query' \
  --data-urlencode 'query=job:claude'

6 - FAQ

Deployment

code-server package not found

Ensure NODE and repo config are in place:

yum repolist    # EL
apt-cache policy   # Debian/Ubuntu, read-only inspection
./infra.yml -l infra -t repo --check

JupyterLab installation failed

jupyter_venv must exist:

uv venv /data/venv
./vibe.yml -l <host> -t jupyter --check
./vibe.yml -l <host> -t jupyter

Access

Cannot access /code/ or /jupyter/

1. Check service status
2. Check port listening
3. Check Nginx config

systemctl status code-server
systemctl status jupyter
ss -tlnp | grep 8443
ss -tlnp | grep 8888
nginx -t

WebSocket connection fails

Ensure Nginx enables WebSocket (default is enabled). If using custom infra_portal, set websocket: true.

Password and Token

Change Code-Server password

Persist the new password in inventory first so it does not enter shell history:

./vibe.yml -l <host> -t code_config,code_launch --check
./vibe.yml -l <host> -t code_config,code_launch

Change JupyterLab token

Persist a high-entropy random token in inventory first. The current template allows any Origin and disables XSRF checks, so never use an example token or expose TCP/8888 directly:

./vibe.yml -l <host> -t jupyter_config --check
./vibe.yml -l <host> -t jupyter_config
ssh <host> sudo systemctl restart jupyter

Claude Code

CLI not found

First check whether claude_install completed:

which claude
npm list -g --depth=0 | grep '@anthropic-ai/claude-code'
./vibe.yml -l <host> -t claude_install

If claude_enabled is disabled, install manually:

npm install -g @anthropic-ai/claude-code

Use claude_package to select a different npm package.

Codex CLI not found

which codex
npm list -g --depth=0 | grep '@openai/codex'
./vibe.yml -l <host> -t codex_install

Confirm that codex_enabled: true. VIBE installs Codex CLI only and does not generate Codex configuration.

API key not set

export ANTHROPIC_API_KEY=sk-ant-xxx
# or set in claude_env

Telemetry not showing

Check local VictoriaMetrics/VictoriaLogs:

curl http://127.0.0.1:8428/api/v1/status/buildinfo
curl http://127.0.0.1:9428/select/logsql/stats_query

Ensure OTEL endpoints in ~/.claude/settings.json are correct.

Extensions and Plugins

Code-Server extension install fails

• Check network
• Try switching code_gallery
• Or install VSIX manually

code-server --install-extension /path/to/extension.vsix

JupyterLab extension install fails

source /data/venv/bin/activate
pip install jupyterlab-git
systemctl restart jupyter