LibreFang
中文

System & Configuration API

Endpoints for system health, configuration, templates, sessions, task queue, backup/restore, migration, and UI bindings.

Template Endpoints

GET /api/templates

List available agent templates from the agents directory.

Response 200 OK:

{
  "templates": [
    {
      "name": "hello-world",
      "description": "A friendly greeting agent",
      "path": "/home/user/.librefang/workspaces/agents/hello-world/agent.toml"
    },
    {
      "name": "coder",
      "description": "Expert coding assistant",
      "path": "/home/user/.librefang/workspaces/agents/coder/agent.toml"
    }
  ],
  "total": 30
}

GET /api/templates/{name}

Get a specific template's manifest and raw TOML.

Response 200 OK:

{
  "name": "hello-world",
  "manifest": {
    "name": "hello-world",
    "description": "A friendly greeting agent",
    "module": "builtin:chat",
    "tags": [],
    "model": {
      "provider": "groq",
      "model": "llama-3.3-70b-versatile"
    },
    "capabilities": {
      "tools": ["file_read", "file_list", "web_fetch"],
      "network": []
    }
  },
  "manifest_toml": "name = \"hello-world\"\nversion = \"0.1.0\"\n..."
}

System Endpoints

GET /api/health

Public health check. Does not require authentication. Returns a redacted subset of system status (no database or agent_count details).

Response 200 OK:

{
  "status": "ok",
  "uptime_seconds": 3600,
  "panic_count": 0,
  "restart_count": 0
}

The status field is "ok" when all systems are healthy, or "degraded" when the database is unreachable.

GET /api/health/detail

Full health check with all dependency status. Requires authentication. Unlike the public /api/health, this endpoint includes database connectivity and agent counts.

Response 200 OK:

{
  "status": "ok",
  "uptime_seconds": 3600,
  "panic_count": 0,
  "restart_count": 0,
  "agent_count": 3,
  "database": "connected",
  "config_warnings": []
}

GET /api/status

Detailed kernel status including all agents.

Response 200 OK:

{
  "status": "running",
  "agent_count": 2,
  "data_dir": "/home/user/.librefang/data",
  "default_provider": "groq",
  "default_model": "llama-3.3-70b-versatile",
  "uptime_seconds": 3600,
  "agents": [
    {
      "id": "a1b2c3d4-...",
      "name": "hello-world",
      "state": "Running",
      "created_at": "2025-01-15T10:30:00Z",
      "model_provider": "groq",
      "model_name": "llama-3.3-70b-versatile"
    }
  ]
}

GET /api/version

Build and version information.

Response 200 OK:

{
  "name": "librefang",
  "version": "0.1.0",
  "build_date": "2025-01-15",
  "git_sha": "abc1234",
  "rust_version": "1.82.0",
  "platform": "linux",
  "arch": "x86_64"
}

POST /api/shutdown

Initiate graceful shutdown. Agent states are preserved to SQLite for restore on next boot.

Response 200 OK:

{
  "status": "shutting_down"
}

GET /api/profiles

List available agent profiles (predefined configurations for common use cases).

Response 200 OK:

{
  "profiles": [
    {
      "name": "coder",
      "tier": "smart",
      "description": "Expert coding assistant"
    },
    {
      "name": "researcher",
      "tier": "frontier",
      "description": "Deep research and analysis"
    }
  ]
}

GET /api/profiles/{name}

Get a specific profile by name.

GET /api/tools

List all available tools that agents can use.

Response 200 OK:

{
  "tools": [
    "file_read",
    "file_write",
    "file_list",
    "web_fetch",
    "web_search",
    "shell_exec",
    "kv_get",
    "kv_set",
    "agent_call"
  ],
  "total": 60
}

GET /api/tools/{name}

Get detailed information about a specific tool including its input schema.

POST /api/tools/{name}/invoke

Invoke a kernel tool directly, without going through an agent loop. Intended for MCP bridges, automation scripts, and out-of-band integrations.

Fail-closed: every request is rejected unless [tool_invoke] enabled = true and the tool name appears in [tool_invoke] allowlist. Approval-gated tools additionally require ?agent_id=<uuid> so the approval callback can resolve back to a real agent — without an agent_id such tools are rejected to avoid orphaned deferred executions.

Request: JSON body is the tool's input object (validated against the tool's schema).

Query parameters:

  • agent_id (optional, must be a well-formed UUID): caller agent for approval-gated tools and audit attribution.

Response statuses:

  • 200 — tool executed; body is the tool's result JSON.
  • 400 — input failed schema validation, or an approval-gated tool was invoked without agent_id.
  • 403 — endpoint disabled or tool not in the allowlist.
  • 404 — tool not registered.
# config.toml
[tool_invoke]
enabled = true
allowlist = ["http_get", "shell_exec"]   # exact tool names

curl -X POST 'http://127.0.0.1:4545/api/tools/http_get/invoke?agent_id=11111111-1111-1111-1111-111111111111' \
  -H 'Authorization: Bearer $LIBREFANG_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com"}'

GET /api/metrics

Prometheus-format metrics endpoint for integration with Grafana, Prometheus, or compatible monitoring stacks.

GET /api/versions

API version discovery. Returns all available API versions and their stability status.

GET /api/openapi.json

Auto-generated OpenAPI 3.0 specification for all API endpoints.

Config Management Endpoints

GET /api/config

Retrieve current kernel configuration (secrets are redacted).

The body mirrors config.toml section for section: top-level scalars stay at the top level, and each [section] becomes a nested object under the same key. Secret values are replaced in place with "***" (set) or "not set" (empty) rather than dropped, so the key is always present. Enum-valued fields use the same spelling config.toml accepts ("allowlist", not "Allowlist"). Every field POST /api/config/set accepts is readable here — a test enforces that (#6596).

Response 200 OK (abbreviated — the real body carries every config section):

{
  "api_listen": "127.0.0.1:4545",
  "api_key": "***",
  "log_level": "info",
  "mode": "default",
  "data_dir": "/home/user/.librefang/data",
  "default_model": {
    "provider": "groq",
    "model": "llama-3.3-70b-versatile",
    "api_key_env": "GROQ_API_KEY",
    "base_url": null
  },
  "exec_policy": {
    "mode": "allowlist",
    "timeout_secs": 30
  },
  "terminal": {
    "enabled": true,
    "allow_remote": false
  },
  "mcp_servers": [{ "name": "filesystem", "timeout_secs": 30, "env_count": 1 }]
}

GET /api/config/schema

Get the JSON Schema for the full config file (~/.librefang/config.toml). Useful for editor integrations and config validation.

POST /api/config/set

Set one allowlisted config value at runtime without restarting.

The field is path, a dot-separated key path of at most three segments, and it must be on the write allowlist — a whole table (default_model) is rejected with 403, its leaves (default_model.model) are accepted. Infrastructure and credential paths (api_key, network.shared_secret, anything ending in _env) stay edit-on-disk.

Request Body:

{
  "path": "default_model.model",
  "value": "gemini-2.5-flash"
}

POST /api/config/reload

Reload configuration from disk (~/.librefang/config.toml).

Session Management Endpoints

GET /api/sessions

List all active sessions across agents.

Response 200 OK:

{
  "sessions": [
    {
      "id": "s1b2c3d4-...",
      "agent_id": "a1b2c3d4-...",
      "agent_name": "coder",
      "message_count": 12,
      "created_at": "2025-01-15T10:30:00Z"
    }
  ]
}

POST /api/sessions/cleanup

Remove old or orphaned sessions from the database.

GET /api/sessions/{id}

Get full details for a specific session including message count and metadata.

DELETE /api/sessions/{id}

Delete a specific session and its conversation history.

Response 200 OK:

{
  "status": "deleted",
  "session_id": "s1b2c3d4-..."
}

PUT /api/sessions/{id}/label

Assign a human-readable label to a session for later retrieval.

Request Body:

{
  "label": "code-review-session-2025-01"
}

Task Queue Endpoints

Inspect and manage the daemon's internal async task queue.

GET /api/tasks/status

Get summary status of the task queue (pending, running, failed counts).

GET /api/tasks/list

List queued and recently completed tasks.

DELETE /api/tasks/{id}

Cancel and remove a queued task.

POST /api/tasks/{id}/retry

Retry a failed task.

GET /api/queue/status

Get the current queue depth and throughput metrics.

Backup & Restore Endpoints

POST /api/backup

Create a full backup of the daemon state (agents, sessions, memory, config).

Response 200 OK:

{
  "filename": "librefang-backup-2025-01-15T10-30-00.tar.gz",
  "size_bytes": 2048576
}

GET /api/backups

List all available backup files.

DELETE /api/backups/{filename}

Delete a backup file.

POST /api/restore

Restore daemon state from a backup file.

Request Body:

{
  "filename": "librefang-backup-2025-01-15T10-30-00.tar.gz"
}

Migration Endpoints

Import data from OpenClaw or other agent frameworks. The migration engine handles YAML-to-TOML manifest conversion, SKILL.md parsing, and session history import.

GET /api/migrate/detect

Auto-detect migration sources on the system. Scans common locations for OpenClaw installations, config files, and agent data.

Response 200 OK:

{
  "sources": [
    {
      "type": "openclaw",
      "path": "/home/user/.openclaw",
      "version": "2.1.0",
      "agents_found": 12,
      "skills_found": 8
    }
  ]
}

POST /api/migrate/scan

Scan a specific path for importable data.

Request Body:

{
  "path": "/home/user/.openclaw"
}

Response 200 OK:

{
  "agents": [
    {
      "name": "my-agent",
      "format": "yaml",
      "convertible": true
    }
  ],
  "skills": [
    {
      "name": "custom-skill",
      "format": "SKILL.md",
      "convertible": true
    }
  ],
  "sessions": 45
}

POST /api/migrate

Run the migration. Converts manifests, imports skills, and optionally imports session history.

Request Body:

{
  "source": "/home/user/.openclaw",
  "import_agents": true,
  "import_skills": true,
  "import_sessions": false
}

Response 200 OK:

{
  "status": "completed",
  "agents_imported": 12,
  "skills_imported": 8,
  "sessions_imported": 0,
  "warnings": [
    "Skill 'legacy-plugin' uses unsupported runtime 'ruby', skipped"
  ]
}

Bindings & Commands Endpoints

GET /api/bindings

List current keyboard/event bindings for the WebChat UI.

POST /api/bindings

Add a new binding.

DELETE /api/bindings/{index}

Remove a binding by its index in the bindings list.

GET /api/commands

List all available slash commands for the WebChat input.

GET /api/commands/{name}

Get details for a specific slash command.