use-vibe-remote

name use-vibe-remote slug use-vibe-remote description Safely inspect and modify local Vibe Remote configuration, routing, runtime settings, watches, scheduled tasks, Vibe Cloud remote access, and operational state. version 0.3.0 Use Vibe Remote Use this skill when the user asks you to configure, repair, explain, or operate a local Vibe Remote installation. Typical requests include: enable a Slack, Discord, Telegram, Lark/Feishu, or WeChat scope route one channel or DM user to OpenCode, Claude, or Codex set a working directory for a channel or DM user choose a backend model, subagent, or reasoning level show or hide intermediate message types configure an outbound proxy ( proxy_url ) for an IM platform that cannot reach its API directly pair, start, stop, or inspect Vibe Cloud remote Web UI access create, update, inspect, pause, resume, or remove a managed background watch with vibe watch create, inspect, run, pause, resume, or remove a scheduled task with vibe task run a one-shot Agent job with vibe agent run , including async background runs inspect or cancel concrete Agent Run records with vibe runs check or apply Vibe Remote updates ( vibe check-update , vibe upgrade ) inspect logs, run doctor, check service status, or explain where Vibe Remote stores state decide whether a requested change belongs in Vibe Remote config or in the host backend's own config Follow this skill as an operations playbook for agents, not as end-user marketing copy. Core Rules Prefer the Web UI API for Vibe Remote configuration changes. Do not hand-edit config files for routine work. Read current API state before mutating. Merge the user's requested change into the current payload. Preserve unrelated scopes, platforms, users, and secrets. Treat secrets as opaque. Do not print, invent, rotate, or overwrite tokens unless the user explicitly provides replacements. Use the smallest viable API call and verify by reading back the API response. For POST /settings , preserve every existing channel for that platform; the endpoint replaces the platform's channel map. For POST /api/users , merge each edited user with its current user payload first; missing user fields are not a patch. Make every persistent-state change through the Web UI API or the vibe CLI. Vibe Remote's internal storage is opaque — do not read, query, or hand-edit it. POST /config persists the new payload but does not restart running platform adapters by itself. When the change is platform credentials, proxy_url , or other transport-level settings, plan an explicit restart afterwards; prefer the delayed CLI form ( vibe restart --delay-seconds 60 ) when triggering it from inside an active conversation. The only credential save that restarts on its own is the WeChat QR-login completion through POST /wechat/qr_login/poll . Do not restart the service by default. Use POST /doctor , GET /status , and read-back checks first. Only start, stop, restart, or reload Vibe Remote when the user explicitly asks or when a change cannot take effect otherwise; explain why before doing it. If an agent must restart Vibe Remote from an active conversation, use vibe restart --delay-seconds 60 so the current session can receive the reply before the restart lands. Tell the user whether the change is global or scope-specific. API First Workflow Use this order when changing Vibe Remote configuration: Determine the Web UI base URL. Default is http://127.0.0.1:5123 . If the user has a custom UI host or port (from ui.setup_host / ui.setup_port ), use that exact origin. When Vibe Cloud remote access is active, the public origin (e.g. https://<slug>.avibe.bot ) also speaks the same API and requires OIDC session cookies — prefer the local origin from the host running Vibe Remote. Check liveness with GET /health or GET /status . Decide whether the request belongs in: POST /config for global defaults, platform credentials, runtime config, agent defaults, UI config, remote-access provider settings, update policy, or global display toggles POST /settings for channel-level routing, working directory, visibility, enablement, and mention policy /api/users and /api/bind-codes for DM user binding and user-scope settings /remote-access/* for Vibe Cloud pairing and tunnel control host backend config instead of Vibe Remote when the request is OpenCode, Claude Code, or Codex native behavior Fetch the current state from the matching GET endpoint. Merge the requested change in memory. Send the mutating request through the Web UI API with CSRF protection. Read back the changed resource and verify the effective payload. Run POST /doctor only when the change affects runtime health, platform credentials, or backend availability. Report the changed scope or global keys and whether a restart was avoided or still required. Calling the Web UI API Mutating API calls require: same-origin Origin or Referer header CSRF cookie named vibe_csrf_token matching X-Vibe-CSRF-Token header Use this local curl pattern: BASE= "http://127.0.0.1:5123" COOKIE_JAR= " $(mktemp) " CSRF= " $( curl -fsS -c " $COOKIE_JAR " " $BASE /api/csrf-token" \ | python3 -c 'import json,sys; print(json.load(sys.stdin) [" csrf_token "])' )" curl -fsS -b " $COOKIE_JAR " -c " $COOKIE_JAR " \ -H "Origin: $BASE " \ -H "X-Vibe-CSRF-Token: $CSRF " \ -H "Content-Type: application/json" \ -X POST " $BASE /doctor" \ --data '{}' For DELETE , use the same cookie jar, Origin , and CSRF header. When the Web UI is served through Vibe Cloud, the same calls require an authenticated OIDC session cookie issued by /auth/callback . Prefer hitting 127.0.0.1:5123 directly from the local machine for maintenance work. Do not log full request bodies when they contain tokens or secrets. Reusable local API helper For multi-step maintenance, use the bundled helper at scripts/vibe_api.py instead of hand-writing curl commands. The helper handles CSRF, same-origin headers, cookies, JSON encoding, and readable error output. Resolve paths relative to this skill directory. If the skill is installed at skills/use-vibe-remote , run: Usage examples: export VIBE_UI_BASE= "http://127.0.0.1:5123" python3 skills/use-vibe-remote/scripts/vibe_api.py GET /health python3 skills/use-vibe-remote/scripts/vibe_api.py GET '/settings?platform=slack' python3 skills/use-vibe-remote/scripts/vibe_api.py POST /doctor '{}' python3 skills/use-vibe-remote/scripts/vibe_api.py POST /config '{"show_duration":true}' python3 skills/use-vibe-remote/scripts/vibe_api.py DELETE '/api/users/U123?platform=slack' Payload can be passed as inline JSON, as @payload.json , or as - to read JSON from stdin. For scope updates, still fetch and merge first: API_HELPER= "skills/use-vibe-remote/scripts/vibe_api.py" python3 " $API_HELPER " GET '/settings?platform=slack' > /tmp/slack_settings.json python3 - << 'PY' import json from pathlib import Path settings = json.loads(Path( "/tmp/slack_settings.json" ).read_text()) channels = settings.get( "channels" ) or {} channels[ "C123" ] = { **channels.get( "C123" , {}), "enabled" : True, "show_message_types" : channels.get( "C123" , {}).get( "show_message_types" ) or [ "assistant" ], "custom_cwd" : channels.get( "C123" , {}).get( "custom_cwd" ), "require_mention" : channels.get( "C123" , {}).get( "require_mention" ), "routing" : { **(channels.get( "C123" , {}).get( "routing" ) or {}), "agent_backend" : "codex" , "codex_model" : "gpt-5.4" , "codex_reasoning_effort" : "high" , }, } Path( "/tmp/slack_payload.json" ).write_text(json.dumps({ "platform" : "slack" , "channels" : channels})) PY python3 " $API_HELPER " POST /settings @/tmp/slack_payload.json python3 " $API_HELPER " GET '/settings?platform=slack' Runtime Layout Vibe Remote stores runtime data under ~/.vibe_remote/ by default (or VIBE_REMOTE_HOME if set). The only paths an agent normally needs: ~/.vibe_remote/config/config.json — global config; mutate through POST /config , not by editing the file ~/.vibe_remote/logs/vibe_remote.log — main application log; read via POST /logs ~/.vibe_remote/screenshots/ — default output directory for vibe screenshot ~/.vibe_remote/state/user_preferences.md — shared long-term preference file (safe to read and update) Agent harness state is managed through vibe agent run , vibe task , vibe watch , and vibe runs (or their API endpoints), not by editing persistence files. Everything else under state/ and runtime/ is internal — treat it as opaque. API Endpoint Reference Health and inspection GET /health returns {"status":"ok"} when the Web UI server is reachable GET /status returns runtime status, running state, PID metadata, and last action GET /doctor reads the latest persisted doctor result POST /doctor runs doctor immediately and returns the result POST /logs payload: {"lines": 500, "source": "service"} source can be service or another source listed in the response; use all for aggregated logs GET /version returns current version and update metadata GET /api/csrf-token issues the vibe_csrf_token cookie and returns the matching token value for X-Vibe-CSRF-Token GET /platforms returns the static catalog of supported IM platforms only (id, config_key, title/description i18n keys, credential field names, capabilities). It does not include enablement or credential-presence state — fetch /config to see which platforms are enabled and whether credentials are configured. Global config GET /config returns the current V2 config payload POST /config accepts a partial object, deep-merges it with current config, validates it through V2Config.from_payload , then persists it use for platform credentials, enabled platforms, primary platform, runtime defaults, agent defaults, UI config, remote-access provider settings, update policy, and global toggles the handler only persists and (for remote_access ) reconciles the cloudflared tunnel; running platform adapters keep using their previous credentials and transport until a restart. Plan a vibe restart --delay-seconds 60 after any credential, proxy_url , or transport-level change. Important config payload shape: { "platform" : "slack" , "platforms" : { "enabled" : [ "slack" , "discord" , "telegram" , "lark" , "wechat" ] , "primary" : "slack" } , "mode" : "self_host" , "version" : "v2" , "slack" : { "bot_token" : "xoxb-..." , "app_token" : "xapp-..." , "signing_secret" : "..." , "team_id" : "T..." , "team_name" : "..." , "app_id" : "A..." , "require_mention" : false , "disable_link_unfurl" : false , "proxy_url" : null } , "discord" : { "bot_token" : "..." , "application_id" : "..." , "require_mention" : false , "thread_auto_archive_minutes" : 10080 , "guild_allowlist" : null , "guild_denylist" : null , "proxy_url" : null } , "telegram" : { "bot_token" : "123:abc" , "require_mention" : true , "forum_auto_topic" : true , "use_webhook" : false , "webhook_url" : null , "webhook_secret_token" : null , "allowed_chat_ids" : null , "allowed_user_ids" : null , "proxy_url" : null } , "lark" : { "app_id" : "..." , "app_secret" : "..." , "require_mention" : false , "domain" : "feishu" , "proxy_url" : null } , "wechat" : { "bot_token" : "..." , "base_url" : "https://ilinkai.weixin.qq.com" , "cdn_base_url" : "https://novac2c.cdn.weixin.qq.com/c2c" , "require_mention" : false , "proxy_url" : null } , "runtime" : { "default_cwd" : "/path/to/workdir" , "log_level" : "INFO" } , "agents" : { "default_backend" : "opencode" , "opencode" : { "enabled" : true , "cli_path" : "opencode" , "default_agent" : null , "default_model" : null , "default_reasoning_effort" : null , "error_retry_limit" : 1 } , "claude" : { "enabled" : true , "cli_path" : "claude" , "default_model" : null , "idle_timeout_seconds" : 600 } , "codex" : { "enabled" : true , "cli_path" : "codex" , "default_model" : null , "idle_timeout_seconds" : 600 } } , "ui" : { "setup_host" : "127.0.0.1" , "setup_port" : 5123 , "open_browser" : true } , "remote_access" : { "provider" : "vibe_cloud" , "vibe_cloud" : { "enabled" : false , "backend_url" : "https://avibe.bot" , "public_url" : "" , "instance_id" : "" , "client_id" : "" , "issuer" : "" , "authorization_endpoint" : "" , "token_endpoint" : "" , "jwks_uri" : "" , "redirect_uri" : "" , "tunnel_token" : "" , "instance_secret" : "" , "session_secret" : "" , "cloudflared_path" : "" , "dev_login_hint" : "" } } , "update" : { "auto_update" : true , "check_interval_minutes" : 60 , "idle_minutes" : 30 , "notify_admins" : true } ,