# 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.

Source: https://developers.cephable.com/docs/automate-http-server

---
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](/docs/automate-http-server/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](/docs/automate-http-server/quick-start)** — enable the extension, copy your key, and make a first run in under five minutes.
- **[API reference](/docs/automate-http-server/api-reference)** — every endpoint, request field, response field, and status code.
- **[Running Automate tasks](/docs/automate-http-server/runs)** — 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](/docs/automate-http-server/custom-tools)** — give the agent your own tools: inline MCP servers, or caller-executed tools with a LangChain-compatible tool-calling loop.
- **[OpenAI compatibility](/docs/automate-http-server/openai-compatibility)** — using `/v1/chat/completions` from existing clients, and exactly which OpenAI features are and are not supported.
- **[Models](/docs/automate-http-server/models)** — list the on-device catalog, pin a model for your integration, and launch Cephable with a model and port preselected.
- **[Security model](/docs/automate-http-server/security)** — what the loopback boundary does and does not protect, key handling, and the filesystem scope rules.
- **[Troubleshooting](/docs/automate-http-server/troubleshooting)** — every error the server returns and what to do about it.
- **[Samples](/docs/automate-http-server/samples)** — four clone-and-run applications on [GitHub](https://github.com/Cephable/Cephable-Automate-Agent-Samples), plus copy-paste clients for Node.js, Python, .NET, shell, and Swift.

---

## Rather clone something that runs?

**[github.com/Cephable/Cephable-Automate-Agent-Samples](https://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](https://github.com/Cephable/Cephable-Automate-Agent-Samples/tree/main/tools/fake-cephable) that speaks this protocol without running a model, so you can build against it before you have a Professional licence.

---

## A one-request example

```bash
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 }
      }'
```

```jsonc
{
  "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 }
}
```