This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Module: VIBE

Deploy AI coding sandbox with Pigsty, including Code-Server, JupyterLab, and Claude Code.

VIBE module provides a complete cloud development environment, integrating browser-based VS Code, interactive computing platform JupyterLab, and AI coding assistant Claude Code. Combined with JuiceFS distributed filesystem and feature-rich PostgreSQL, it creates a ready-to-use AI coding sandbox.


Components

VIBE module includes three core components:

ComponentDescriptionDefault PortAccess Path
Code-ServerVS Code in browser, full cloud IDE experience8443/code/
JupyterLabInteractive computing, Notebook/terminal/editor8888/jupyter/
Claude CodeAnthropic’s AI coding assistant CLI with observability-CLI / Dashboard

Architecture

VIBE components deploy as systemd services, exposed via Nginx reverse proxy with HTTPS:

User Browser
    │
    ├── https://h.pigsty/code/     ─────► Code-Server  (127.0.0.1:8443)
    ├── https://h.pigsty/jupyter/  ─────► JupyterLab   (127.0.0.1:8888)
    └── https://h.pigsty:3000/d/claude-code ──► Grafana Dashboard

Command Line
    └── ssh [email protected] ──► Claude Code CLI

Shared Storage
    └── JuiceFS (/fs) ─────► PostgreSQL (metadata + data)

Features

  • Cloud IDE: Access full VS Code dev environment via browser, code anywhere
  • Interactive Computing: JupyterLab provides Notebook, terminal, editor multi-functional interface
  • AI Assistant: Claude Code CLI with OpenTelemetry observability for monitoring and analysis
  • Shared Storage: JuiceFS enables filesystem sharing with point-in-time recovery (PITR)
  • Rich PostgreSQL: 400+ extensions pre-installed covering vector, timeseries, geo, analytics
  • One-Click Deploy: Automated installation via Ansible playbooks, ready out-of-box

Quick Start

1. Prepare Config

Use vibe config template:

./configure -c vibe

2. Deploy Infrastructure

./deploy.yml    # Deploy INFRA + PGSQL
./juice.yml     # Deploy JuiceFS shared storage (optional)

3. Deploy VIBE Module

./vibe.yml      # Deploy Code-Server + JupyterLab + Claude Code

4. Access Services

ServiceURLDefault Credential
Code-Serverhttps://<ip>/code/Code.Server
JupyterLabhttps://<ip>/jupyter/Jupyter.Lab
Claude Monitorhttps://<ip>:3000/d/claude-codeGrafana creds

Config Example

Typical VIBE configuration (see conf/vibe.yml):

all:
  children:
    infra:
      hosts:
        10.10.10.10:
          # VIBE component config
          vibe_data: /fs                    # Working directory (JuiceFS mount)
          code_enabled: true                # Enable Code-Server
          code_password: 'Code.Server'      # Code-Server password
          jupyter_enabled: true             # Enable JupyterLab
          jupyter_password: 'Jupyter.Lab'   # JupyterLab Token
          claude_enabled: true              # Enable Claude Code

          # JuiceFS shared storage
          juice_instances:
            jfs:
              path: /fs
              meta: postgres://dbuser_meta:[email protected]:5432/meta
              data: --storage postgres --bucket postgres://dbuser_meta:[email protected]:5432/meta?prefix=juice

Pre-installed Tools

VIBE config template includes these development tools:

ToolDescription
claudeAnthropic Claude Code CLI
opencodeOpen-source AI coding assistant
code-serverVS Code in browser
golangGo language toolchain
nodejsNode.js runtime
uvHigh-performance Python package manager
postgrestPostgreSQL RESTful API service
genai-toolboxGoogle GenAI Toolbox MCP service
resticIncremental backup tool
rcloneCloud storage sync tool
asciinemaTerminal recording tool

PostgreSQL Extensions

VIBE template PostgreSQL includes rich extensions:

  • Vector Search: pgvector, pgvectorscale
  • Time Series: timescaledb, pg_timeseries
  • Geospatial: postgis, h3, pgrouting
  • Analytics: pg_duckdb, pg_analytics, hydra
  • Full-text Search: pg_search, zhparser
  • Security: pg_tde, supabase_vault, pgsodium
  • More: See Extension Catalog

Use Cases

  • AI-Assisted Dev: Use Claude Code for intelligent coding, boost productivity
  • Data Science: JupyterLab + PostgreSQL + vector/timeseries extensions for analytics platform
  • Remote Dev: Access full dev environment via browser on any device
  • Training: Quickly setup standardized learning environments
  • Prototyping: Rapidly build PoC environments, validate technical solutions

Notes


Documentation

  • Configuration: How to configure VIBE module components
  • Parameters: All VIBE module config parameters
  • Playbook: Deploy and manage VIBE with Ansible playbooks
  • Administration: Daily management and operations guide
  • Monitoring: Monitoring metrics and Dashboard guide
  • FAQ: Common questions and answers

1 - VIBE Config

VIBE module configuration guide, including Code-Server, JupyterLab and Claude Code setup.

VIBE module provides flexible configuration options to enable/disable components and customize their behavior.


Overview

VIBE module contains three independently configurable components:

ComponentEnable ParamDefaultDescription
Code-Servercode_enabledenabledVS Code in browser
JupyterLabjupyter_enabledenabledInteractive computing env
Claude Codeclaude_enabledenabledAI coding assistant CLI

Configuration in Pigsty config file host/group vars:

all:
  children:
    infra:
      hosts:
        10.10.10.10:
          # VIBE config
          vibe_data: /fs
          code_enabled: true
          jupyter_enabled: true
          claude_enabled: true

Code-Server Config

Basic Settings

code_enabled: true           # Enable Code-Server
code_port: 8443              # Listen port (localhost only)
code_data: /data/code        # User data directory
code_password: 'Code.Server' # Login password
code_gallery: openvsx        # Extension marketplace

Extension Marketplace

Code-Server supports multiple extension marketplaces:

OptionDescription
openvsxOpen VSX marketplace (default)
microsoftMicrosoft official marketplace

China mainland users auto-use Tsinghua mirror for acceleration.

Example

# Use Microsoft extension marketplace
code_enabled: true
code_password: 'MySecretPassword'
code_gallery: microsoft
code_data: /data/code

JupyterLab Config

Basic Settings

jupyter_enabled: true           # Enable JupyterLab
jupyter_port: 8888              # Listen port
jupyter_data: /data/jupyter     # Data directory
jupyter_password: 'Jupyter.Lab' # Login Token
jupyter_venv: /data/venv        # Python venv path

Python Virtual Environment

JupyterLab runs in Python venv, needs pre-creation:

# Create venv
python3 -m venv /data/venv

# Install JupyterLab (VIBE playbook auto-installs)
/data/venv/bin/pip install jupyterlab ipykernel

Example

# Custom JupyterLab config
jupyter_enabled: true
jupyter_password: 'MySecretToken'
jupyter_port: 8888
jupyter_data: /data/jupyter
jupyter_venv: /data/venv

Claude Code Config

Basic Settings

claude_enabled: true   # Enable Claude Code
claude_env: {}         # Extra environment variables

Configure API Key

Claude Code requires API Key. Pass via claude_env:

claude_enabled: true
claude_env:
  ANTHROPIC_API_KEY: sk-ant-xxx-your-api-key

Or configure manually after deployment:

# Set env var
export ANTHROPIC_API_KEY=sk-ant-xxx-your-api-key

# Or use Claude Code config command
claude config set apiKey sk-ant-xxx-your-api-key

OpenTelemetry Config

Claude Code includes OpenTelemetry observability by default, auto-pushing metrics and logs to VictoriaMetrics/VictoriaLogs:

  • Metrics endpoint: http://127.0.0.1:8428/opentelemetry/v1/metrics
  • Logs endpoint: http://127.0.0.1:9428/insert/opentelemetry/v1/logs

Config file at ~/.claude/settings.json.


Working Directory

vibe_data param specifies shared working directory for all VIBE components:

vibe_data: /fs   # Default uses JuiceFS mount point

This directory is used for:

  • Code-Server default open directory
  • JupyterLab Notebook root directory
  • Claude Code working directory

Recommend using with JuiceFS for:

  • Distributed filesystem high availability
  • PostgreSQL-based PITR capability
  • File sharing across nodes

Complete Examples

Minimal Config

all:
  children:
    infra:
      hosts:
        10.10.10.10:
          code_enabled: true

Standard Config

all:
  children:
    infra:
      hosts:
        10.10.10.10:
          # Working directory
          vibe_data: /fs

          # Code-Server
          code_enabled: true
          code_port: 8443
          code_password: 'Code.Server'
          code_gallery: openvsx

          # JupyterLab
          jupyter_enabled: true
          jupyter_port: 8888
          jupyter_password: 'Jupyter.Lab'
          jupyter_venv: /data/venv

          # Claude Code
          claude_enabled: true
          claude_env:
            ANTHROPIC_API_KEY: sk-ant-xxx

AI Coding Sandbox Config

Complete AI coding sandbox config with JuiceFS shared storage:

all:
  vars:
    version: v3.4.0
    admin_ip: 10.10.10.10
    infra_portal:
      home: { domain: h.pigsty }
      grafana: { domain: g.pigsty, endpoint: "${admin_ip}:3000" }
      prometheus: { domain: p.pigsty, endpoint: "${admin_ip}:9090" }
      alertmanager: { domain: a.pigsty, endpoint: "${admin_ip}:9093" }
      code: { domain: code.pigsty, endpoint: "127.0.0.1:8443", websocket: true }
      jupyter: { domain: jupyter.pigsty, endpoint: "127.0.0.1:8888", websocket: true }

    # PostgreSQL config
    pg_cluster: pg-meta
    pg_databases:
      - name: meta

    # JuiceFS config
    juice_instances:
      jfs:
        path: /fs
        meta: postgres://dbuser_meta:[email protected]:5432/meta
        data: --storage postgres --bucket postgres://dbuser_meta:[email protected]:5432/meta?prefix=juice

  children:
    infra:
      hosts:
        10.10.10.10:
          # VIBE config
          vibe_data: /fs
          code_enabled: true
          code_password: 'YourSecurePassword'
          jupyter_enabled: true
          jupyter_password: 'YourSecureToken'
          claude_enabled: true
          claude_env:
            ANTHROPIC_API_KEY: sk-ant-xxx

Disable Components

To disable specific components:

# Only enable Code-Server
code_enabled: true
jupyter_enabled: false
claude_enabled: false

# Only enable JupyterLab
code_enabled: false
jupyter_enabled: true
claude_enabled: false

# Only enable Claude Code
code_enabled: false
jupyter_enabled: false
claude_enabled: true

Or disable via command line when running playbook:

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

Nginx Reverse Proxy

VIBE components exposed via Nginx reverse proxy. Related config in infra_portal:

infra_portal:
  # Sub-path mode (default)
  home: { domain: h.pigsty }

  # Sub-domain mode (optional)
  code: { domain: code.pigsty, endpoint: "127.0.0.1:8443", websocket: true }
  jupyter: { domain: jupyter.pigsty, endpoint: "127.0.0.1:8888", websocket: true }

Access methods:

  • Sub-path: https://h.pigsty/code/, https://h.pigsty/jupyter/
  • Sub-domain: https://code.pigsty, https://jupyter.pigsty

2 - VIBE Params

VIBE module parameter reference, covering all configurable options for Code-Server, JupyterLab and Claude Code.

VIBE module has 13 config parameters, grouped into: common params, Code-Server params, JupyterLab params, and Claude Code params.


Parameter Overview

ParameterTypeLevelDefaultDescription
vibe_datapathH/I/fsVIBE working directory
code_enabledboolH/ItrueEnable Code-Server
code_portportH/I8443Code-Server listen port
code_datapathH/I/data/codeCode-Server data dir
code_passwordstringH/ICode.ServerCode-Server password
code_galleryenumH/IopenvsxExtension marketplace type
jupyter_enabledboolH/ItrueEnable JupyterLab
jupyter_portportH/I8888JupyterLab listen port
jupyter_datapathH/I/data/jupyterJupyterLab data dir
jupyter_passwordstringH/IJupyter.LabJupyterLab Token
jupyter_venvpathH/I/data/venvPython venv path
claude_enabledboolH/ItrueEnable Claude Code
claude_envdictH/I{}Claude Code extra env vars

Common Parameters

vibe_data

VIBE module working directory, default working path for all components.

  • Type: path
  • Level: H/I (Host/Instance)
  • Default: /fs

Used for:

  • Code-Server default open directory
  • JupyterLab Notebook root directory
  • Claude Code working directory
  • Store CLAUDE.md and AGENTS.md context files

Recommend using JuiceFS mount point for distributed storage and PITR capability.

vibe_data: /fs              # Default, JuiceFS mount point
vibe_data: /home/dev/work   # Custom working directory

Code-Server Parameters

code_enabled

Whether to enable Code-Server on this node.

  • Type: bool
  • Level: H/I
  • Default: true
code_enabled: true   # Enabled (default)
code_enabled: false  # Disabled

code_port

Code-Server listen port, binds to localhost only.

  • Type: port
  • Level: H/I
  • Default: 8443

External access via Nginx reverse proxy, no need to expose this port directly.

code_port: 8443   # Default port
code_port: 9443   # Custom port

code_data

Code-Server user data directory, stores extensions, user settings, etc.

  • Type: path
  • Level: H/I
  • Default: /data/code

Directory structure:

/data/code/
├── code-server/
│   ├── config.yaml      # Config file
│   ├── extensions/      # Installed extensions
│   └── User/
│       └── settings.json # User settings
└── ...
code_data: /data/code      # Default path
code_data: /home/dev/code  # Custom path

code_password

Code-Server login password.

  • Type: string
  • Level: H/I
  • Default: Code.Server
code_password: 'Code.Server'     # Default (change it!)
code_password: 'MySecretPass!'   # Custom password

Code-Server extension marketplace type.

  • Type: enum
  • Level: H/I
  • Default: openvsx
  • Options: openvsx, microsoft
OptionDescription
openvsxOpen VSX marketplace (default)
microsoftMicrosoft VS Code marketplace

China mainland auto-uses Tsinghua mirror.

code_gallery: openvsx    # Open VSX (default)
code_gallery: microsoft  # Microsoft marketplace

JupyterLab Parameters

jupyter_enabled

Whether to enable JupyterLab on this node.

  • Type: bool
  • Level: H/I
  • Default: true
jupyter_enabled: true   # Enabled (default)
jupyter_enabled: false  # Disabled

jupyter_port

JupyterLab listen port.

  • Type: port
  • Level: H/I
  • Default: 8888

JupyterLab binds to 0.0.0.0, but typically accessed via Nginx reverse proxy.

jupyter_port: 8888   # Default port
jupyter_port: 8899   # Custom port

jupyter_data

JupyterLab data directory, stores config files and kernel info.

  • Type: path
  • Level: H/I
  • Default: /data/jupyter

Directory structure:

/data/jupyter/
├── jupyter_config.py   # JupyterLab config
└── kernels/            # Jupyter kernels
jupyter_data: /data/jupyter      # Default path
jupyter_data: /home/dev/jupyter  # Custom path

jupyter_password

JupyterLab login Token.

  • Type: string
  • Level: H/I
  • Default: Jupyter.Lab
jupyter_password: 'Jupyter.Lab'   # Default (change it!)
jupyter_password: 'MySecretToken' # Custom Token

jupyter_venv

Python virtual environment path for JupyterLab.

  • Type: path
  • Level: H/I
  • Default: /data/venv

Directory structure:

/data/venv/
└── bin/
    ├── python
    ├── pip
    └── jupyter
jupyter_venv: /data/venv          # Default path
jupyter_venv: /home/dev/.venv     # Custom path

Claude Code Parameters

claude_enabled

Whether to enable Claude Code CLI configuration on this node.

  • Type: bool
  • Level: H/I
  • Default: true
claude_enabled: true   # Enabled (default)
claude_enabled: false  # Disabled

claude_env

Extra environment variables for Claude Code, used for API Key etc.

  • Type: dict
  • Level: H/I
  • Default: {}

Common environment variables:

VariableDescription
ANTHROPIC_API_KEYAnthropic API key
ANTHROPIC_BASE_URLCustom API endpoint
# Configure API Key
claude_env:
  ANTHROPIC_API_KEY: sk-ant-xxx-your-api-key

# Configure custom API endpoint
claude_env:
  ANTHROPIC_API_KEY: sk-ant-xxx
  ANTHROPIC_BASE_URL: https://api.example.com

Parameter Level Reference

LevelDescription
GGlobal param, defined in all.vars
CCluster param, defined at cluster level
IInstance param, defined at host level
HHost param, specific to single host

VIBE module params are all H/I level, defined at host or instance level. Different hosts can have different values:

all:
  children:
    infra:
      hosts:
        10.10.10.10:
          code_enabled: true
          code_password: 'Password1'
        10.10.10.11:
          code_enabled: true
          code_password: 'Password2'

Default Values Summary

# VIBE common params
vibe_data: /fs

# Code-Server params
code_enabled: true
code_port: 8443
code_data: /data/code
code_password: 'Code.Server'
code_gallery: openvsx

# JupyterLab params
jupyter_enabled: true
jupyter_port: 8888
jupyter_data: /data/jupyter
jupyter_password: 'Jupyter.Lab'
jupyter_venv: /data/venv

# Claude Code params
claude_enabled: true
claude_env: {}

3 - VIBE Playbook

VIBE module Ansible playbook usage, including deployment, update and management operations.

VIBE module provides one main playbook vibe.yml for deploying and managing Code-Server, JupyterLab and Claude Code.


Playbook Overview

PlaybookDescription
vibe.ymlDeploy VIBE dev environment (Code, Jupyter, Claude) on target nodes

vibe.yml

vibe.yml playbook deploys VIBE module on managed nodes.

Playbook Content

- name: Deploy VIBE development environment
  hosts: all
  become: yes
  gather_facts: no
  roles:
    - { role: node_id, tags: id }
    - { role: vibe, tags: vibe }

Usage

# Full deployment (all components)
./vibe.yml -l <host>

# Deploy Code-Server only
./vibe.yml -l <host> -t code

# Deploy JupyterLab only
./vibe.yml -l <host> -t jupyter

# Deploy Claude Code only
./vibe.yml -l <host> -t claude

# Disable specific component
./vibe.yml -l <host> -e code_enabled=false
./vibe.yml -l <host> -e jupyter_enabled=false
./vibe.yml -l <host> -e claude_enabled=false

# Configure Claude API Key
./vibe.yml -l <host> -e claude_env.ANTHROPIC_API_KEY=sk-ant-xxx

Task Structure

vibe.yml playbook contains these task hierarchies:

vibe
├── vibe_dir          # Create working dir and render context files
├── claude            # Configure Claude Code CLI
│   ├── claude_install    # Install claude package
│   └── claude_config     # Render config files
├── code              # Deploy Code-Server
│   ├── code_install      # Install code-server package
│   ├── code_dir          # Create data directory
│   ├── code_config       # Render config and systemd unit
│   └── code_launch       # Start code-server service
└── jupyter           # Deploy JupyterLab
    ├── jupyter_install   # Install JupyterLab to venv
    ├── jupyter_dir       # Create data directory
    ├── jupyter_config    # Render config and systemd unit
    └── jupyter_launch    # Start JupyterLab service

Task Details

vibe_dir

Create VIBE working directory and render context files.

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

Actions:

  • Create {{ vibe_data }} directory (default /fs)
  • Render CLAUDE.md environment doc
  • Create AGENTS.md symlink

claude

Configure Claude Code CLI.

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

Sub-tasks:

TagDescription
claude_installInstall claude package
claude_configRender ~/.claude.json and ~/.claude/settings.json

Config file contents:

  • ~/.claude.json: Skip onboarding dialog
  • ~/.claude/settings.json: OpenTelemetry config

code

Deploy Code-Server.

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

Sub-tasks:

TagDescription
code_installInstall code-server package
code_dirCreate {{ code_data }} data directory
code_configRender config.yaml, systemd unit, env file
code_launchStart/restart code-server service

Generated files:

  • /etc/systemd/system/code-server.service
  • /etc/default/code
  • {{ code_data }}/code-server/config.yaml

jupyter

Deploy JupyterLab.

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

Sub-tasks:

TagDescription
jupyter_installInstall JupyterLab to Python venv
jupyter_dirCreate {{ jupyter_data }} data directory
jupyter_configRender jupyter_config.py, systemd unit, env file
jupyter_launchStart/restart JupyterLab service

Generated files:

  • /etc/systemd/system/jupyter.service
  • /etc/default/jupyter
  • {{ jupyter_data }}/jupyter_config.py

Common Commands

Full Deployment

# Deploy on single host
./vibe.yml -l 10.10.10.10

# Deploy on multiple hosts
./vibe.yml -l '10.10.10.10,10.10.10.11'

# Deploy on specified group
./vibe.yml -l infra

Component-Level Deployment

# Deploy Code-Server only
./vibe.yml -l <host> -t code

# Deploy JupyterLab only
./vibe.yml -l <host> -t jupyter

# Deploy Claude Code only
./vibe.yml -l <host> -t claude

Config Update

# Update Code-Server config and restart
./vibe.yml -l <host> -t code_config,code_launch

# Update JupyterLab config and restart
./vibe.yml -l <host> -t jupyter_config,jupyter_launch

# Update Claude Code config
./vibe.yml -l <host> -t claude_config

Restart Service Only

# Restart Code-Server
./vibe.yml -l <host> -t code_launch

# Restart JupyterLab
./vibe.yml -l <host> -t jupyter_launch

Parameter Override

# Custom password
./vibe.yml -l <host> -e code_password='MyPassword'
./vibe.yml -l <host> -e jupyter_password='MyToken'

# Disable component
./vibe.yml -l <host> -e code_enabled=false
./vibe.yml -l <host> -e jupyter_enabled=false
./vibe.yml -l <host> -e claude_enabled=false

# Configure Claude API Key
./vibe.yml -l <host> -e "claude_env={ANTHROPIC_API_KEY: 'sk-ant-xxx'}"

# Use Microsoft extension marketplace
./vibe.yml -l <host> -e code_gallery=microsoft

Deployment Order

VIBE module depends on these components, deploy in order:

# 1. Deploy infrastructure (INFRA module)
./infra.yml

# 2. Deploy PostgreSQL (PGSQL module)
./pgsql.yml

# 3. Deploy JuiceFS shared storage (optional, JUICE module)
./juice.yml

# 4. Deploy VIBE development environment
./vibe.yml

Or use one-click deploy:

./deploy.yml  # Includes INFRA + PGSQL
./juice.yml   # JuiceFS (optional)
./vibe.yml    # VIBE

Idempotency

VIBE playbook supports idempotent execution:

  • Repeatable: Multiple executions have no side effects
  • Incremental: Only updates changed configs
  • Auto-restart: Related services restart after config changes
# First deployment
./vibe.yml -l <host>

# Re-run after config change (safe)
./vibe.yml -l <host>

Execution Protection

Limit Target Hosts

Use -l param to limit execution scope:

# Execute on specified host only
./vibe.yml -l 10.10.10.10

# Execute on specified group only
./vibe.yml -l infra

Preview Mode

Use --check param to preview changes:

./vibe.yml -l <host> --check

Verbose Output

Use -v param for detailed output:

./vibe.yml -l <host> -v      # Verbose
./vibe.yml -l <host> -vv     # More verbose
./vibe.yml -l <host> -vvv    # Debug level

4 - VIBE Admin

VIBE module administration guide, including service management, password changes, extension installation.

This guide covers daily VIBE module operations including service management, config modification, extension installation and common SOPs.


Service Management

Code-Server Service

# Check service status
sudo systemctl status code-server

# Start service
sudo systemctl start code-server

# Stop service
sudo systemctl stop code-server

# Restart service
sudo systemctl restart code-server

# Enable at boot
sudo systemctl enable code-server

# Disable at boot
sudo systemctl disable code-server

JupyterLab Service

# Check service status
sudo systemctl status jupyter

# Start service
sudo systemctl start jupyter

# Stop service
sudo systemctl stop jupyter

# Restart service
sudo systemctl restart jupyter

# Enable at boot
sudo systemctl enable jupyter

# Disable at boot
sudo systemctl disable jupyter

View Service Logs

# Code-Server logs
journalctl -u code-server -f

# JupyterLab logs
journalctl -u jupyter -f

# View last 100 lines
journalctl -u code-server -n 100
journalctl -u jupyter -n 100

Password Management

Change Code-Server Password

Method 1: Edit config file

# Edit config file
sudo vi /data/code/code-server/config.yaml

# Modify password field
password: YourNewPassword

# Restart service
sudo systemctl restart code-server

Method 2: Use Ansible

# Modify code_password in pigsty.yml
# Then execute
./vibe.yml -l <host> -t code_config,code_launch

Change JupyterLab Token

Method 1: Edit config file

# Edit config file
sudo vi /data/jupyter/jupyter_config.py

# Modify c.ServerApp.token value
c.ServerApp.token = 'YourNewToken'

# Restart service
sudo systemctl restart jupyter

Method 2: Use Ansible

# Modify jupyter_password in pigsty.yml
# Then execute
./vibe.yml -l <host> -t jupyter_config,jupyter_launch

Extension Management

Code-Server Extensions

Install via Web UI

  1. Open Code-Server (https://<host>/code/)
  2. Click Extensions icon on left sidebar
  3. Search and install desired extensions

Install via CLI

# Install single extension
code-server --install-extension ms-python.python

# Install from VSIX file
code-server --install-extension /path/to/extension.vsix

# List installed extensions
code-server --list-extensions

# Uninstall extension
code-server --uninstall-extension ms-python.python

Switch Extension Marketplace

Modify code_gallery param:

# Open VSX (default)
code_gallery: openvsx

# Microsoft official marketplace
code_gallery: microsoft

Then redeploy:

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

JupyterLab Extensions

Install JupyterLab Extensions

# Activate venv
source /data/venv/bin/activate

# Install extension
pip install jupyterlab-git
pip install jupyterlab-lsp

# Restart JupyterLab
sudo systemctl restart jupyter

Python Package Management

Install Python Packages

# Activate venv
source /data/venv/bin/activate

# Install with pip
pip install numpy pandas matplotlib scikit-learn

# Use Tsinghua mirror (China)
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple numpy pandas

# Install with uv (faster)
uv pip install numpy pandas matplotlib

Configure pip Mirror

# Temporary use
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple <package>

# Permanent config
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

Install Jupyter Kernel

# Install ipykernel
pip install ipykernel

# Register new kernel
python -m ipykernel install --user --name myenv --display-name "Python (myenv)"

# List registered kernels
jupyter kernelspec list

# Remove kernel
jupyter kernelspec remove myenv

Claude Code Management

Configure API Key

Method 1: Environment variable

# Temporary
export ANTHROPIC_API_KEY=sk-ant-xxx-your-api-key

# Permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export ANTHROPIC_API_KEY=sk-ant-xxx-your-api-key' >> ~/.bashrc
source ~/.bashrc

Method 2: Claude config command

claude config set apiKey sk-ant-xxx-your-api-key

Method 3: Configure during Ansible deployment

claude_env:
  ANTHROPIC_API_KEY: sk-ant-xxx-your-api-key

View Claude Config

# View current config
cat ~/.claude.json
cat ~/.claude/settings.json

# View Claude version
claude --version

Using Claude Code

# Start Claude in current directory
claude

# Start in specified directory
claude /path/to/project

# Non-interactive mode
claude -p "Explain this code"

# Specify model
claude --model claude-sonnet-4-20250514

Directory Structure

VIBE Working Directory

{{ vibe_data }}           # Default /fs
├── CLAUDE.md             # Claude Code context file
├── AGENTS.md             # Symlink -> CLAUDE.md
└── <your-projects>/      # Project files

Code-Server Data Directory

{{ code_data }}           # Default /data/code
└── code-server/
    ├── config.yaml       # Config file
    ├── extensions/       # Extensions directory
    └── User/
        └── settings.json # User settings

JupyterLab Data Directory

{{ jupyter_data }}        # Default /data/jupyter
├── jupyter_config.py     # Config file
└── kernels/              # Jupyter kernels

Python Virtual Environment

{{ jupyter_venv }}        # Default /data/venv
├── bin/
│   ├── python
│   ├── pip
│   ├── jupyter
│   └── ...
├── lib/
│   └── python3.x/
│       └── site-packages/
└── ...

Config File Locations

ComponentConfig File
Code-Server/data/code/code-server/config.yaml
Code-Server/etc/systemd/system/code-server.service
Code-Server/etc/default/code
JupyterLab/data/jupyter/jupyter_config.py
JupyterLab/etc/systemd/system/jupyter.service
JupyterLab/etc/default/jupyter
Claude Code~/.claude.json
Claude Code~/.claude/settings.json

Connect to PostgreSQL

From JupyterLab

import psycopg2

# Connect to database
conn = psycopg2.connect(
    'postgres://dbuser_dba:[email protected]:5432/meta'
)
cursor = conn.cursor()

# Execute query
cursor.execute('SELECT version()')
print(cursor.fetchone())

# Close connection
cursor.close()
conn.close()

Using pandas

import pandas as pd
import psycopg2

conn = psycopg2.connect(
    'postgres://dbuser_dba:[email protected]:5432/meta'
)
df = pd.read_sql('SELECT * FROM pg_stat_activity', conn)
df.head()

From Code-Server Terminal

# Using psql
psql postgres://dbuser_dba:[email protected]:5432/meta

# Using pgcli (if installed)
pgcli postgres://dbuser_dba:[email protected]:5432/meta

Backup and Restore

Backup Code-Server Config

# Backup user data
tar -czvf code-backup.tar.gz /data/code

# Restore
tar -xzvf code-backup.tar.gz -C /
sudo systemctl restart code-server

Backup JupyterLab Config

# Backup config and notebooks
tar -czvf jupyter-backup.tar.gz /data/jupyter /fs/*.ipynb

# Restore
tar -xzvf jupyter-backup.tar.gz -C /
sudo systemctl restart jupyter

Using JuiceFS PITR

If working directory uses JuiceFS, leverage PostgreSQL PITR for point-in-time recovery. See JUICE Admin Guide.


Troubleshooting

Service Won’t Start

# View detailed error logs
journalctl -u code-server -xe
journalctl -u jupyter -xe

# Check port usage
ss -tlnp | grep 8443
ss -tlnp | grep 8888

# Check processes
ps aux | grep code-server
ps aux | grep jupyter

Cannot Access Web UI

# Check Nginx status
sudo systemctl status nginx

# Check Nginx config
sudo nginx -t

# Check firewall
sudo firewall-cmd --list-all

JupyterLab Python Version Issues

# Check Python version in venv
/data/venv/bin/python --version

# Check JupyterLab version
/data/venv/bin/jupyter --version

# Rebuild venv
rm -rf /data/venv
python3 -m venv /data/venv
/data/venv/bin/pip install jupyterlab ipykernel

5 - VIBE Monitor

VIBE module monitoring integration, including Claude Code observability and Dashboard usage.

VIBE module provides complete observability support, especially Claude Code’s OpenTelemetry integration for monitoring AI coding assistant usage via Grafana Dashboard.


Monitoring Architecture

Claude Code CLI
    │
    ├── OpenTelemetry Metrics ──► VictoriaMetrics (8428)
    └── OpenTelemetry Logs    ──► VictoriaLogs    (9428)
                                       │
                                       ▼
                               Grafana Dashboard
                               (Claude Code Dashboard)

Claude Code Observability

OpenTelemetry Config

Claude Code includes OpenTelemetry by default, auto-pushing metrics and logs to local VictoriaMetrics/VictoriaLogs:

Config file ~/.claude/settings.json:

{
  "otelEndpointMetrics": "http://127.0.0.1:8428/opentelemetry/v1/metrics",
  "otelEndpointLogs": "http://127.0.0.1:9428/insert/opentelemetry/v1/logs",
  "otelResourceAttributes": {
    "ip": "10.10.10.10",
    "job": "claude"
  }
}

Monitoring Metrics

Claude Code reports these main metrics:

Metric TypeDescription
SessionSession count, duration
TokenInput/output token count, cost stats
API CallsRequest count, latency, error rate
Tool UsageTool call counts (Read, Write, Bash, etc.)

Log Data

Claude Code logs include:

  • Session start/end events
  • User prompts and assistant responses
  • Tool call details
  • Errors and warnings

Grafana Dashboard

Access Dashboard

Claude Code Dashboard accessible at:

https://<ip>:3000/d/claude-code

Login with Grafana credentials (default: admin / pigsty).

Dashboard Features

PanelDescription
Session OverviewActive sessions, total sessions
Token UsageInput/output token trends, cost analysis
API PerformanceRequest latency, error rate
Tool Usage StatsTool call frequency, duration distribution
Session LogsDetailed session records and conversations

System Service Monitoring

Using systemd Monitoring

# Check Code-Server status
systemctl status code-server

# Check JupyterLab status
systemctl status jupyter

# View service logs
journalctl -u code-server -f
journalctl -u jupyter -f

Port Checks

# Check Code-Server port (8443)
ss -tlnp | grep 8443

# Check JupyterLab port (8888)
ss -tlnp | grep 8888

# Use curl to check services
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8443
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8888

Health Checks

Automated Health Check Script

#!/bin/bash
# vibe-health-check.sh

echo "=== VIBE Service Health Check ==="

# Code-Server
if systemctl is-active --quiet code-server; then
    echo "[OK] Code-Server: Running"
else
    echo "[ERROR] Code-Server: Not running"
fi

# JupyterLab
if systemctl is-active --quiet jupyter; then
    echo "[OK] JupyterLab: Running"
else
    echo "[ERROR] JupyterLab: Not running"
fi

# Port checks
if ss -tlnp | grep -q ":8443 "; then
    echo "[OK] Code-Server port 8443: Listening"
else
    echo "[ERROR] Code-Server port 8443: Not listening"
fi

if ss -tlnp | grep -q ":8888 "; then
    echo "[OK] JupyterLab port 8888: Listening"
else
    echo "[ERROR] JupyterLab port 8888: Not listening"
fi

Endpoint Checks with curl

# Check Code-Server
curl -s -o /dev/null -w "%{http_code}\n" \
    --connect-timeout 5 \
    http://127.0.0.1:8443/healthz

# Check JupyterLab
curl -s -o /dev/null -w "%{http_code}\n" \
    --connect-timeout 5 \
    http://127.0.0.1:8888/api/status

Alert Configuration

Service Down Alerts

Configure VIBE service alerts in Alertmanager:

# Example: Code-Server down alert
- alert: CodeServerDown
  expr: up{job="code-server"} == 0
  for: 5m
  labels:
    severity: warning
  annotations:
    summary: "Code-Server service down"
    description: "Code-Server on {{ $labels.instance }} has been down for over 5 minutes"

# Example: JupyterLab down alert
- alert: JupyterLabDown
  expr: up{job="jupyter"} == 0
  for: 5m
  labels:
    severity: warning
  annotations:
    summary: "JupyterLab service down"
    description: "JupyterLab on {{ $labels.instance }} has been down for over 5 minutes"

Log Management

Log Locations

ComponentLog Location
Code-Serverjournalctl -u code-server
JupyterLabjournalctl -u jupyter
Claude CodeVictoriaLogs / ~/.claude/logs/

Log Queries

Using journalctl

# View recent logs
journalctl -u code-server -n 100

# View specific time range
journalctl -u code-server --since "2024-01-01" --until "2024-01-02"

# Real-time follow
journalctl -u code-server -f

Query Claude logs via VictoriaLogs

# Query via Grafana Explore panel
# Or use vlogs API
curl -G 'http://localhost:9428/select/logsql/query' \
    --data-urlencode 'query={job="claude"}'

Resource Monitoring

View Resource Usage

# View Code-Server resource usage
systemctl status code-server
ps aux | grep code-server

# View JupyterLab resource usage
systemctl status jupyter
ps aux | grep jupyter

# View memory usage
free -h

# View disk usage
df -h /data
df -h /fs

JuiceFS Storage Monitoring

If using JuiceFS as working directory:

# View JuiceFS status
juicefs status /fs

# View filesystem usage
df -h /fs

# View file stats
juicefs info /fs

Performance Tuning

Code-Server Performance Optimization

# Increase file handle limit (already in systemd service)
# /etc/systemd/system/code-server.service
LimitNOFILE=65535

JupyterLab Performance Optimization

# /data/jupyter/jupyter_config.py

# Increase max buffer size
c.ServerApp.max_buffer_size = 1073741824  # 1GB

# Configure timeout
c.ServerApp.shutdown_no_activity_timeout = 0  # Disable auto-shutdown

6 - VIBE FAQ

VIBE module frequently asked questions covering deployment, configuration, and usage.

This document covers common questions and solutions for VIBE module usage.


Deployment Issues

How to use VIBE config template?

# Download Pigsty
curl https://repo.pigsty.io/get | bash

# Use vibe config template
./configure -c vibe

# Modify passwords then deploy
vi pigsty.yml
./deploy.yml
./juice.yml   # Optional
./vibe.yml

Error “code-server package not found”

Ensure repos are properly configured:

# Check repo availability
yum repolist          # EL systems
apt update            # Debian/Ubuntu

# Refresh repo cache
./infra.yml -t repo

JupyterLab Installation Fails

Check if Python venv exists:

# Check venv
ls -la /data/venv/bin/python

# If not exists, create manually
python3 -m venv /data/venv

# Re-run playbook
./vibe.yml -l <host> -t jupyter

Access Issues

Cannot Access Code-Server

  1. Check service status

    systemctl status code-server
    
  2. Check port listening

    ss -tlnp | grep 8443
    
  3. Check Nginx config

    nginx -t
    systemctl status nginx
    
  4. Check firewall

    firewall-cmd --list-all
    

Cannot Access JupyterLab

  1. Check service status

    systemctl status jupyter
    
  2. Check port listening

    ss -tlnp | grep 8888
    
  3. Verify Token

    Ensure using correct Token, default is Jupyter.Lab.

WebSocket Connection Failed

JupyterLab and Code-Server both depend on WebSocket. Ensure Nginx config is correct:

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

Check infra_portal config has WebSocket enabled:

infra_portal:
  code: { domain: code.pigsty, endpoint: "127.0.0.1:8443", websocket: true }
  jupyter: { domain: jupyter.pigsty, endpoint: "127.0.0.1:8888", websocket: true }

Password and Authentication

How to Change Code-Server Password?

Method 1: Edit config directly

vi /data/code/code-server/config.yaml
# Modify password field
systemctl restart code-server

Method 2: Use Ansible

# Modify code_password in pigsty.yml
./vibe.yml -l <host> -t code_config,code_launch

How to Change JupyterLab Token?

Method 1: Edit config directly

vi /data/jupyter/jupyter_config.py
# Modify c.ServerApp.token
systemctl restart jupyter

Method 2: Use Ansible

# Modify jupyter_password in pigsty.yml
./vibe.yml -l <host> -t jupyter_config,jupyter_launch

Forgot Password?

View password from config files:

# Code-Server password
grep password /data/code/code-server/config.yaml

# JupyterLab Token
grep token /data/jupyter/jupyter_config.py

Claude Code Issues

Claude Code Not Working

  1. Check if API Key is configured

    echo $ANTHROPIC_API_KEY
    cat ~/.claude.json
    
  2. Configure API Key

    export ANTHROPIC_API_KEY=sk-ant-xxx
    # Or
    claude config set apiKey sk-ant-xxx
    

Claude Code Cannot Connect to API

  1. Check network

    curl -I https://api.anthropic.com
    
  2. Check proxy settings

    echo $HTTP_PROXY
    echo $HTTPS_PROXY
    

Claude Code Monitoring Data Not Showing

Check if OpenTelemetry endpoints are reachable:

# Check VictoriaMetrics
curl http://127.0.0.1:8428/api/v1/status/buildinfo

# Check VictoriaLogs
curl http://127.0.0.1:9428/select/logsql/stats_query

Confirm ~/.claude/settings.json is configured correctly.


Extensions and Plugins

Code-Server Extension Installation Fails

  1. Check network connection

    curl -I https://open-vsx.org
    
  2. Switch extension marketplace

    code_gallery: microsoft  # Switch to Microsoft marketplace
    

    Redeploy:

    ./vibe.yml -l <host> -t code_config,code_launch
    
  3. Manual VSIX install

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

How to Use GitHub Copilot?

GitHub Copilot doesn’t support Code-Server. Consider:

  • Use Claude Code as AI coding assistant
  • Use Codeium or other Code-Server compatible AI tools

JupyterLab Extension Installation Fails

# Activate venv
source /data/venv/bin/activate

# Check JupyterLab version
jupyter --version

# Install extension
pip install jupyterlab-git

# Restart service
systemctl restart jupyter

Python and Jupyter

JupyterLab Won’t Start

  1. Check venv

    /data/venv/bin/python --version
    /data/venv/bin/jupyter --version
    
  2. Reinstall JupyterLab

    /data/venv/bin/pip install --upgrade jupyterlab ipykernel
    
  3. Check logs

    journalctl -u jupyter -xe
    

How to Install Additional Python Packages?

# Activate venv
source /data/venv/bin/activate

# Install packages
pip install numpy pandas matplotlib

# Use Tsinghua mirror (China)
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple numpy pandas

How to Add New Jupyter Kernel?

# Install ipykernel
pip install ipykernel

# Register kernel
python -m ipykernel install --user --name myenv --display-name "Python (myenv)"

# List kernels
jupyter kernelspec list

How to Connect to PostgreSQL?

import psycopg2

conn = psycopg2.connect(
    'postgres://dbuser_dba:[email protected]:5432/meta'
)
cursor = conn.cursor()
cursor.execute('SELECT version()')
print(cursor.fetchone())
conn.close()

Performance and Resources

Code-Server Laggy

  1. Check memory usage

    free -h
    ps aux | grep code-server
    
  2. Disable unnecessary extensions

    Disable unused extensions in Code-Server.

  3. Add system resources

    Consider increasing VM memory.

JupyterLab Notebook Runs Slow

  1. Check kernel resources

    top
    htop
    
  2. Clear Notebook output

    Clearing cell outputs reduces memory usage.

  3. Restart kernel

    Periodically restart kernel to release memory.

Disk Space Low

# Check disk usage
df -h

# Clean logs
journalctl --vacuum-time=7d

# Clean pip cache
pip cache purge

JuiceFS Integration

Working Directory Unavailable

  1. Check JuiceFS mount

    mount | grep juicefs
    df -h /fs
    
  2. Remount

    ./juice.yml -l <host>
    

Filesystem Performance Poor

  1. Check network latency

    ping <postgresql-host>
    
  2. Check PostgreSQL status

    psql postgres://... -c "SELECT 1"
    

Security Issues

How to Restrict Access?

  1. Configure firewall

    # Allow specific IP only
    firewall-cmd --add-rich-rule='rule family="ipv4" source address="10.0.0.0/8" port port="443" protocol="tcp" accept'
    
  2. Use Nginx access control

    location /code/ {
        allow 10.0.0.0/8;
        deny all;
        ...
    }
    

Are Default Passwords Secure?

No! Always change in production:

  • code_password: Default Code.Server
  • jupyter_password: Default Jupyter.Lab
code_password: 'YourStrongPassword!'
jupyter_password: 'YourStrongToken!'

Supported Platforms

Which Operating Systems?

SystemVersions
EL8, 9, 10
Ubuntu20.04, 22.04, 24.04
Debian11, 12, 13

Which Architectures?

  • x86_64 (AMD64)
  • ARM64 (AArch64)

Ansible Version Requirement?

Minimum: Ansible 2.9+