codebuddy --serve --port 8080 --session-id my-session

curl http://127.0.0.1:8080/api/v1/health
# {"data":{"status":"ok","uptime":12.3,"platforms":["generic","wecom","wechat-kf"]}}

X-CodeBuddy-Request: 1

CODEBUDDY_CODE_CORS_ORIGINS=http://localhost:5173 codebuddy --serve

  Endpoint    http://127.0.0.1:8321
  Web UI      http://127.0.0.1:8321/?password=<generated password>

  Password    <generated password>
  Config      ~/.codebuddy/settings.json

codebuddy --serve --auth none
# or
CODEBUDDY_GATEWAY_AUTH=none codebuddy --serve

# 1) Bearer Token (recommended, also carries security headers)
curl -H "X-CodeBuddy-Request: 1" \\
     -H "Authorization: Bearer YOUR_PASSWORD" \\
     http://host:port/api/v1/sessions

# 2) X-Access-Token (equivalent to Bearer, aligned with the credential header convention of E2B envd)
curl -H "X-CodeBuddy-Request: 1" \\
     -H "X-Access-Token: YOUR_PASSWORD" \\
     http://host:port/api/v1/sessions

# 3) Cookie (automatically carried by the browser after login)
curl -H "X-CodeBuddy-Request: 1" \\
     -H "Cookie: gateway_session=<sha256(password)>" \\
     http://host:port/api/v1/sessions

// Success
{
    "data": { ... }
}

// Error
{
    "error": {
        "code": "AUTH_REQUIRED",      // Machine-readable error code
        "message": "Authentication required"  // Human-readable description
    }
}

# Dispatch Background Agent
curl -H "X-CodeBuddy-Request: 1" \\
  -H "Authorization: Bearer $PASSWORD" \\
  -H 'Content-Type: application/json' \\
  -X POST http://127.0.0.1:8080/api/v1/jobs \\
  -d '{"prompt":"Check the test status of the current repository","cwd":"/repo/app"}'

# Subscribe to job List Changes
curl -N -H "X-CodeBuddy-Request: 1" \\
  -H "Authorization: Bearer $PASSWORD" \\
  http://127.0.0.1:8080/api/v1/jobs/events

-H "X-CodeBuddy-Request: 1" -H "Authorization: Bearer $PASSWORD"

curl http://127.0.0.1:8080/api/v1/health

# Send a message (the body must be in Gateway Protocol format, and id/type are required)
curl -X POST http://127.0.0.1:8080/api/v1/runs \\
  -H "Content-Type: application/json" \\
  -H "X-CodeBuddy-Request: 1" \\
  -d '{
    "id": "run-1",
    "type": "message",
    "source": {"platform": "generic", "sender": {"id": "dev", "name": "Developer"}, "conversation": {"id": "run-1", "type": "direct"}},
    "payload": {"text": "Help me analyze the code performance"}
  }'

# Response: {"data": {"runId": "uuid-xxx", "status": "accepted"}}

# Obtain results through an SSE stream (the X-CodeBuddy-Request header is also required)
curl -H "X-CodeBuddy-Request: 1" http://127.0.0.1:8080/api/v1/runs/uuid-xxx/stream

# Create a terminal
curl -X POST http://127.0.0.1:8080/api/v1/pty \\
  -H "Content-Type: application/json" \\
  -d '{"cols": 120, "rows": 40}'

# List terminals
curl http://127.0.0.1:8080/api/v1/pty

# Stream output over SSE (instead of WebSocket)
curl http://127.0.0.1:8080/api/v1/pty/SESSION_ID/output

# Send input.
curl -X POST http://127.0.0.1:8080/api/v1/pty/SESSION_ID/input/send \\
  -H "Content-Type: application/json" \\
  -d '{"data": "ls -la\\n"}'

# Resize
curl -X POST http://127.0.0.1:8080/api/v1/pty/SESSION_ID/resize \\
  -H "Content-Type: application/json" \\
  -d '{"cols": 200, "rows": 50}'

# Terminate a terminal
curl -X DELETE http://127.0.0.1:8080/api/v1/pty/SESSION_ID

# Download files.
curl "http://127.0.0.1:8080/api/v1/files/download?path=/tmp/test.txt"

# Upload documents.
curl -X POST "http://127.0.0.1:8080/api/v1/files/upload?path=/tmp/upload.txt" \\
  -H "Content-Type: application/octet-stream" \\
  --data-binary @local-file.txt

# Get file information.
curl -X POST http://127.0.0.1:8080/api/v1/fs/stat \\
  -H "Content-Type: application/json" \\
  -d '{"path": "/tmp"}'

# List directories.
curl -X POST http://127.0.0.1:8080/api/v1/fs/list \\
  -H "Content-Type: application/json" \\
  -d '{"path": "/tmp", "depth": 2}'

# Create a directory.
curl -X POST http://127.0.0.1:8080/api/v1/fs/mkdir \\
  -H "Content-Type: application/json" \\
  -d '{"path": "/tmp/new-dir"}'

# Fuzzy file search (CBC enhancement)
curl "http://127.0.0.1:8080/api/v1/fs/search?query=component&limit=10"

# Start a process (JSON mode)
curl -X POST http://127.0.0.1:8080/api/v1/process/start \\
  -H "Content-Type: application/json" \\
  -d '{"process": {"cmd": "python3", "args": ["script.py"]}, "tag": "my-script"}'

# Start a process (SSE streaming output)
curl -X POST http://127.0.0.1:8080/api/v1/process/start \\
  -H "Content-Type: application/json" \\
  -H "Accept: text/event-stream" \\
  -d '{"process": {"cmd": "python3", "args": ["script.py"]}}'

# List running processes.
curl http://127.0.0.1:8080/api/v1/process/list

# Send stdin.
curl -X POST http://127.0.0.1:8080/api/v1/process/input/send \\
  -H "Content-Type: application/json" \\
  -d '{"process": {"pid": 12345}, "input": {"stdin": "hello\\n"}}'

# Send a signal (SIGTERM).
curl -X POST http://127.0.0.1:8080/api/v1/process/signal/send \\
  -H "Content-Type: application/json" \\
  -d '{"process": {"tag": "my-script"}, "signal": 15}'

# System metrics + instance process metrics
curl http://127.0.0.1:8080/api/v1/metrics
# Response: { data: { ts, cpuCount, cpuUsedPct, memTotalMib, memUsedMib, diskUsed, diskTotal, instances: [{ id, cwd, pid, rssMib, heapUsedMib, heapTotalMib, uptimeSeconds, ... }] } }

# Get the session list of the current workspace.
curl http://127.0.0.1:8080/api/v1/sessions

# Get the session list of all workspaces.
curl http://127.0.0.1:8080/api/v1/sessions?cwd=*

# Get the session list of a specified working directory.
curl http://127.0.0.1:8080/api/v1/sessions?cwd=/path/to/workspace

# Get the session list of a specified project (filtered by compressed working directory name).
curl http://127.0.0.1:8080/api/v1/sessions?cwd=*&projectId=workspace-hash

# Rename a session.
curl -X POST http://127.0.0.1:8080/api/v1/sessions/SESSION_ID/rename \\
  -H "Content-Type: application/json" \\
  -d '{"name": "Performance optimization discussion"}'

# Get the file diff (the file must be tracked in a checkpoint).
curl -X POST http://127.0.0.1:8080/internal/file-changes/diff \\
  -H "Content-Type: application/json" \\
  -d '{"path": "/path/to/file.ts"}'
# Response: {"data": {"path": "/path/to/file.ts", "oldText": "...", "newText": "..."}}

# List rollback-able checkpoints.
curl -X POST http://127.0.0.1:8080/internal/file-changes/checkpoints \\
  -H "Content-Type: application/json" \\
  -d '{}'
# Response: {"data": {"checkpoints": [{"id": "xxx", "label": "...", "createdAt": 1234567890, "files": [...], "additions": 5, "deletions": 2}]}}

# Revert changes by file.
curl -X POST http://127.0.0.1:8080/internal/file-changes/revert \\
  -H "Content-Type: application/json" \\
  -d '{"paths": ["/path/to/file.ts"]}'
# Response: {"data": {"success": true, "revertedFiles": ["/path/to/file.ts"]}}

# Roll back to a specified checkpoint.
curl -X POST http://127.0.0.1:8080/internal/file-changes/revert \\
  -H "Content-Type: application/json" \\
  -d '{"checkpointId": "checkpoint-uuid", "scope": "CodeAndConversation"}'
# Possible values for scope: "Code" (revert files only), "Conversation" (revert conversations only), "CodeAndConversation" (revert both).

# Revert all changes (roll back to the earliest checkpoint).
curl -X POST http://127.0.0.1:8080/internal/file-changes/revert \\
  -H "Content-Type: application/json" \\
  -d '{}'

# List installed plugins (each item includes the isBuiltIn boolean field, indicating whether it belongs to the built-in marketplace).
curl http://127.0.0.1:8080/api/v1/plugins

# List only user-installed plugins, filtering out those from the built-in marketplace.
curl "http://127.0.0.1:8080/api/v1/plugins?includeBuiltin=false"

# Install a plugin (in the "name@marketplace" format)
curl -X POST http://127.0.0.1:8080/api/v1/plugins \\
  -H "Content-Type: application/json" \\
  -d '{"plugin": "my-plugin@my-marketplace"}'

# Enable a plugin.
curl -X POST http://127.0.0.1:8080/api/v1/plugins/enable \\
  -H "Content-Type: application/json" \\
  -d '{"plugin": "my-plugin@my-marketplace"}'

# Disable a plugin.
curl -X POST http://127.0.0.1:8080/api/v1/plugins/disable \\
  -H "Content-Type: application/json" \\
  -d '{"plugin": "my-plugin@my-marketplace"}'

# Uninstall a plugin.
curl -X POST http://127.0.0.1:8080/api/v1/plugins/uninstall \\
  -H "Content-Type: application/json" \\
  -d '{"plugin": "my-plugin@my-marketplace"}'

# Update a plugin to the latest version (pass waitForApply=true to wait for the rebuild to take effect before returning).
curl -X POST http://127.0.0.1:8080/api/v1/plugins/update \\
  -H "Content-Type: application/json" \\
  -d '{"plugin": "my-plugin@my-marketplace"}'

# List the plugin marketplace (each item includes the isBuiltIn boolean field).
curl http://127.0.0.1:8080/api/v1/plugins/marketplaces

# List only user-added marketplaces, filtering out built-in ones.
curl "http://127.0.0.1:8080/api/v1/plugins/marketplaces?includeBuiltin=false"

# Add a plugin marketplace.
curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces \\
  -H "Content-Type: application/json" \\
  -d '{"source": "https://example.com/marketplace", "name": "my-marketplace"}'

# Add a plugin marketplace and enable automatic updates by default (equivalent to adding it and then calling marketplaces/auto-update once).
curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces \\
  -H "Content-Type: application/json" \\
  -d '{"source": "https://example.com/marketplace", "name": "my-marketplace", "autoUpdate": true}'

# Browse plugins in the marketplace.
curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces/browse \\
  -H "Content-Type: application/json" \\
  -d '{"marketplace": "my-marketplace"}'

# Update the marketplace (actually pull the latest content from the remote source).
curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces/update \\
  -H "Content-Type: application/json" \\
  -d '{"marketplace": "my-marketplace"}'

# Enable or disable automatic updates for the marketplace (after enabling, the backend periodically syncs and upgrades installed plugins).
curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces/auto-update \\
  -H "Content-Type: application/json" \\
  -d '{"marketplace": "my-marketplace", "autoUpdate": true}'

# Delete a plugin marketplace.
curl -X DELETE http://127.0.0.1:8080/api/v1/plugins/marketplaces/my-marketplace