Cephable Logo
CephableDevelopers
Navigate

Automate HTTP Server

Drive Cephable's on-device Automate assistant from any local program over HTTP. A loopback API in the Cephable desktop app that runs the same agent, tools, skills, and local model the app itself uses — with nothing leaving the device.

The Automate HTTP Server is an opt-in local API built into the Cephable desktop app. When you enable it, Cephable listens on 127.0.0.1 and accepts JSON requests that run the shipping Automate assistant — the same agent loop, system prompt, tool set, AI Skills, MCP servers, approval gates, and local llama.cpp model that the in-app AI Workflows panel uses.

Anything on the machine that can make an HTTP request can now ask Cephable to do work: a Python script, a Node CLI, a .NET desktop app, an Automator or Shortcuts action, a Stream Deck plugin, a switch-input companion app, or a test harness.

your program ──HTTP──▶ 127.0.0.1:4317 ──▶ Cephable main process
                                            │
                                            ├─ WorkflowChannel
                                            ├─ workflow utility process (deepagents)
                                            ├─ Cephable tools · AI Skills · MCP servers
                                            └─ shared llama.cpp server (local GGUF)

Because the request travels the app's own path, you get real agent behavior — planning, tool calls, file work, web research, document generation, human-in-the-loop questions, destructive-tool approvals — not a bare text completion against a GGUF.

Why this exists

You want to… The server gives you…
Add an AI action to an internal tool without sending data to a cloud model A local endpoint; inference and tool execution stay on the device
Let a script do real work on the machine (files, apps, email drafts, research) The full Cephable tool set behind one POST
Turn an accessible input — a switch, sensor, or companion app — into a rich task A single HTTP call per task, with structured step-by-step results
Regression-test prompts, skills, or workflows Deterministic-ish runs with steps, traces, token usage, and timing in the response
Use an existing OpenAI-compatible client or eval framework A non-streaming POST /v1/chat/completions that runs the whole assistant

What makes it different from a model server

A local llama.cpp or Ollama endpoint gives you the model. This gives you the assistant:

  • Tools. ~55 built-in tools across observe / act / transform / output — file search and editing, shell commands, app and UI automation, clipboard and typing, web search and research, email drafts, Google Docs/Sheets/Slides, document generation, text generation, summarization, and translation.
  • Your own tools. Point a run at an MCP server you host, or declare tools by JSON Schema that the agent calls back to your process to execute — which is what makes LangChain's bind_tools work against Cephable unmodified. See Custom tools.
  • AI Skills. The user's installed skills are available to an API run, selected per run by relevance the same way they are in the app.
  • MCP servers. Configured MCP connections are resolved (secrets injected, OAuth refreshed) in the main process and offered to the run.
  • Guardrails. Destructive tools pause for approval; API runs reject them unless the caller explicitly opts in. Human-in-the-loop questions are answered from the request or the run is canceled rather than hanging.
  • Runtime reality. The response tells you which acceleration backend, which GGUF, and which context window actually served the run.

Requirements

  • The Cephable desktop app, running and signed in. The server lives in the app process; closing Cephable stops it.
  • A Cephable Professional account. The extension is gated behind the enableAutomateHttpServer feature flag and will not appear for accounts without it.
  • Secure OS storage available (Windows DPAPI, macOS Keychain, or a real Linux keyring — not the basic_text fallback). The access key is stored encrypted; without secure storage the server refuses to start.
  • The client must run on the same machine. The listener binds 127.0.0.1 only.

Where to go next

  • Quick start — enable the extension, copy your key, and make a first run in under five minutes.
  • API reference — every endpoint, request field, response field, and status code.
  • Running Automate tasks — the /v1/runs contract in depth: answer contracts, workspace scoping, continuations, skills and MCP selection, approvals, and how to read steps, trace, and usage.
  • Custom tools — give the agent your own tools: inline MCP servers, or caller-executed tools with a LangChain-compatible tool-calling loop.
  • OpenAI compatibility — using /v1/chat/completions from existing clients, and exactly which OpenAI features are and are not supported.
  • Models — list the on-device catalog, pin a model for your integration, and launch Cephable with a model and port preselected.
  • Security model — what the loopback boundary does and does not protect, key handling, and the filesystem scope rules.
  • Troubleshooting — every error the server returns and what to do about it.
  • Samples — four clone-and-run applications on GitHub, plus copy-paste clients for Node.js, Python, .NET, shell, and Swift.

Rather clone something that runs?

github.com/Cephable/Cephable-Automate-Agent-Samples has four complete applications — a Python/LangChain agent with custom tools, a WinUI app combining Cephable with Windows' own on-device AI, a Next.js chat UI on the Vercel AI SDK, and a hardened gateway for exposing one machine remotely. Each runs from a clean clone with one command, and each has a demo script for showing it to someone.

It also ships a fake server that speaks this protocol without running a model, so you can build against it before you have a Professional licence.

A one-request example

curl -sS http://127.0.0.1:4317/v1/runs \
  -H "Authorization: Bearer $CEPHABLE_AUTOMATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "prompt": "Summarize the newest .md file in my Documents folder in three bullets.",
        "include": { "events": false, "trace": false }
      }'

{
  "schemaVersion": 1,
  "requestId": "automate-run-2f1c…",
  "status": "completed",
  "answer": "Here are the three key points…",
  "startedAt": "2026-09-14T18:02:11.004Z",
  "completedAt": "2026-09-14T18:02:48.771Z",
  "durationMs": 37767,
  "model": "gemma-4-…-Q4_K_M.gguf",
  "appVersion": "4.2.1",
  "backend": { "flavorId": "vulkan", "accelerator": "vulkan", "cpuFallback": false },
  "steps": [ /* every tool call, in order */ ],
  "usage": { "inputTokens": 5120, "outputTokens": 344, "tps": 41.2, "ttftMs": 610, "generationMs": 8345 }
}