Flvx API

What it does

When your agent uses it

• User wants to manage FLVX panel programmatically
• Via natural language

Example prompts

• “/flvx-api”

Requirements

• Python 3
• Node.js

Workflow steps

6 steps, taken from the first numbered list in SKILL.md.

1. 1⚠️ NO "Bearer" prefix - Authorization: , NOT Authorization: Bearer
2. 2All endpoints use POST - Including list/get operations
3. 3code === 0 means success - Any other value is an error
4. 4Traffic units: User.flow is GB, in_flow/out_flow are bytes
5. 5Timestamps: All timestamps are milliseconds since epoch
6. 6Token is session-scoped: Cache in memory only, not on disk

What it can do on your machine

Read from SKILL.md and the folder at commit d930303. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • curl
  • jq
  • npm

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md. Its commands use curl and npm, which can reach the network depending on how they are called.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names these keys or tokens, usually read from environment variables:

  • FLVX_PASSWORD

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Flvx API loads about 2.4k tokens when it runs, and up to ~20k if it reads all its reference files. Until then it costs about 62 tokens; SKILL.md has 400 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~62

When it runs · the whole SKILL.md, loaded when a task matches

~2.4k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~20k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

• NoteMentions a .env fileSKILL.md:35

  **Security tip:** Add to `~/.flvx/.env` and source on demand:

• NoteMentions a .env fileSKILL.md:37

  mkdir -p ~/.flvx && cat > ~/.flvx/.env << 'EOF'

• NoteMentions a .env fileSKILL.md:42

  chmod 600 ~/.flvx/.env

• NoteMentions a .env fileSKILL.md:43

  source ~/.flvx/.env

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from Sagit-chu/flvx at commit d930303, republished under its GPL-3.0 licence (© Sagit-chu). 400 words, ~2,443 tokens.

name

flvx-api

description

Operate FLVX traffic forwarding management system via REST API. Supports user/node/tunnel/forward management, federation clustering, and traffic monitoring. Use when user wants to manage FLVX panel programmatically or via natural language.

metadata.author

FLVX Team

metadata.version

2.1.5

metadata.requires_env

FLVX_BASE_URL, FLVX_USERNAME, FLVX_PASSWORD

export FLVX_BASE_URL="https://your-panel.example.com"
export FLVX_USERNAME="admin"
export FLVX_PASSWORD="your-password"

mkdir -p ~/.flvx && cat > ~/.flvx/.env << 'EOF'
export FLVX_BASE_URL="https://panel.example.com"
export FLVX_USERNAME="admin"
export FLVX_PASSWORD="your-password"
EOF
chmod 600 ~/.flvx/.env
source ~/.flvx/.env

Before ANY API call:
1. Check if TOKEN is cached in current session
   ├─ Yes → Use cached token, proceed
   └─ No → 
       1. Read FLVX_USERNAME and FLVX_PASSWORD from environment
       2. POST /api/v1/user/login with credentials
       3. Cache response.data.token in session memory
       4. Proceed with original request

curl -X POST "${FLVX_BASE_URL}/api/v1/user/login" \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"${FLVX_USERNAME}\",\"password\":\"${FLVX_PASSWORD}\"}"

{
  "code": 0,
  "msg": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "name": "Administrator",
    "role_id": 0,
    "requirePasswordChange": false
  },
  "ts": 1706659200000
}

User request → Check env vars → Auto-login if needed → Call API → Return result

#!/bin/bash
BASE_URL="${FLVX_BASE_URL}"
USERNAME="${FLVX_USERNAME}"
PASSWORD="${FLVX_PASSWORD}"

# Login and get token
TOKEN=$(curl -s -X POST "${BASE_URL}/api/v1/user/login" \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"${USERNAME}\",\"password\":\"${PASSWORD}\"}" | jq -r '.data.token')

if [ "$TOKEN" == "null" ] || [ -z "$TOKEN" ]; then
  echo "Login failed"
  exit 1
fi

# Use token for API calls - NOTE: NO "Bearer" prefix!
curl -s -X POST "${BASE_URL}/api/v1/node/list" \
  -H "Authorization: ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{}' | jq '.'

import os
import requests

BASE_URL = os.environ.get("FLVX_BASE_URL")
USERNAME = os.environ.get("FLVX_USERNAME")
PASSWORD = os.environ.get("FLVX_PASSWORD")

# Login
resp = requests.post(f"{BASE_URL}/api/v1/user/login", 
    headers={"Content-Type": "application/json"},
    json={"username": USERNAME, "password": PASSWORD})
result = resp.json()
if result["code"] != 0:
    raise Exception(f"Login failed: {result['msg']}")

TOKEN = result["data"]["token"]

# Authenticated request - NO "Bearer" prefix!
headers = {
    "Content-Type": "application/json",
    "Authorization": TOKEN
}
resp = requests.post(f"{BASE_URL}/api/v1/node/list", headers=headers, json={})
print(resp.json())

const BASE_URL = process.env.FLVX_BASE_URL;
const USERNAME = process.env.FLVX_USERNAME;
const PASSWORD = process.env.FLVX_PASSWORD;

// Login
const loginRes = await fetch(`${BASE_URL}/api/v1/user/login`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ username: USERNAME, password: PASSWORD })
});
const loginData = await loginRes.json();
if (loginData.code !== 0) throw new Error(loginData.msg);
const TOKEN = loginData.data.token;

// Authenticated request - NO "Bearer" prefix!
const res = await fetch(`${BASE_URL}/api/v1/node/list`, {
  method: 'POST',
  headers: { 
    'Content-Type': 'application/json',
    'Authorization': TOKEN
  },
  body: JSON.stringify({})
});
console.log(await res.json());

{"code": 0, "msg": "success", "data": {...}, "ts": 1706659200000}

{"code": -1, "msg": "用户名或密码错误", "ts": 1706659200000}

1. Parse JSON response
2. If code === 0 → return data
3. If code === 401 → token expired, re-login and retry
4. If code === 403 → permission denied, need admin
5. Else → show msg to user as error message

1. POST /api/v1/user/create → Create user with traffic quota
2. POST /api/v1/tunnel/user/assign → Assign tunnels to user
3. Tell user their username/password
4. User logs in and creates forwards

1. POST /api/v1/node/create → Register node in panel
2. POST /api/v1/node/install → Get install command
3. Run install command on target server
4. POST /api/v1/node/check-status → Verify node is online

1. POST /api/v1/tunnel/user/tunnel → List available tunnels
2. POST /api/v1/forward/create → Create forward on chosen tunnel
3. POST /api/v1/forward/diagnose → Verify connectivity

1. POST /api/v1/node/list → Check node statuses
2. POST /api/v1/node/releases → Check available versions
3. POST /api/v1/node/upgrade or /batch-upgrade → Upgrade nodes
4. POST /api/v1/node/rollback → Rollback if needed

© Sagit-chu, GPL-3.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 15 other files (references) in skills/flvx-api of Sagit-chu/flvx.

• SKILL.md
• package.json
• references/auth.md
• references/backup.md
• references/config.md
• references/errors.md
• references/examples/curl-examples.md
• references/examples/http-client.md
• references/federation.md
• references/forwards.md
• references/groups.md
• references/nodes.md
• references/speed-limits.md
• references/tunnels.md
• references/types.md
• references/users.md

Open the folder on GitHubat commit d930303