Quick Start — Automate HTTP Server

Five minutes from a fresh install to a working agent run. Everything happens on your own machine.

Prerequisites

Cephable desktop app installed, running, and signed in to a Cephable Professional account
At least one tool-capable on-device model downloaded in Cephable (the app prompts for this the first time you use AI Workflows)
Any HTTP client — curl, Node.js, Python, .NET, PowerShell

1. Enable the extension

In Cephable, open Extensions.
Under Cephable features → Build & Extend, find Automate HTTP Server.
Enable it from the card.
Open the card's detail view and confirm the status reads Running.

The detail view shows three things you need:

Field	Meaning
Endpoint	The base URL to call, e.g. `http://127.0.0.1:4317`
Port	The port actually bound. If `4317` was taken, Cephable moves to the next free port and says so
Access key	The bearer token for every request

Read the Endpoint value rather than hardcoding 4317. Cephable scans up to twelve consecutive ports (4317–4328) when its preferred port is in use — a second Cephable instance or a stale process is enough to move it.

2. Copy the access key

Click Copy access key in the detail view.

The key is 43 characters of URL-safe base64, generated on first use and stored encrypted with your operating system's secure storage. It is never synced to Cephable's servers and never appears in a launch argument.

Put it in an environment variable rather than in your source:

# macOS / Linux
export CEPHABLE_AUTOMATE_KEY='paste-key-here'

# Windows PowerShell
$env:CEPHABLE_AUTOMATE_KEY = 'paste-key-here'

Regenerate access key invalidates the previous key immediately — every client using the old one starts getting 401.

3. Check the connection

GET /health is the cheapest way to prove the server is up, the key is right, and the assistant is ready. Note that /health requires the bearer token too — there are no anonymous routes.

curl -sS http://127.0.0.1:4317/health \
  -H "Authorization: Bearer $CEPHABLE_AUTOMATE_KEY"

{
  "status": "ok",
  "service": "cephable-agent",
  "appVersion": "4.2.1",
  "platform": "win32",
  "workflowStatus": "idle",
  "busy": false,
  "workerRunning": false,
  "modelName": "gemma-4-…-Q4_K_M.gguf",
  "workspace": "C:\Users\you\AppData\Roaming\Cephable\automate-http-workspace",
  "backend": { "flavorId": "vulkan", "accelerator": "vulkan", "cpuFallback": false },
  "contextSize": 16384
}

You are ready to run when busy is false and workflowStatus is idle or terminated.

401 → wrong or regenerated key.
Connection refused → the extension is off, Cephable is closed, or the server moved to another port. See Troubleshooting.

4. Run your first task

curl -sS http://127.0.0.1:4317/v1/runs \
  -H "Authorization: Bearer $CEPHABLE_AUTOMATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "prompt": "List the three largest files in my Downloads folder with their sizes.",
        "include": { "events": false, "trace": false }
      }'

The request blocks until the run finishes. There is no streaming and no job id to poll — a real agent run takes tens of seconds to a few minutes, so set a generous client-side timeout. The server's own default is 15 minutes.

The response is the full run record:

{
  "schemaVersion": 1,
  "requestId": "automate-run-9c2e…",
  "status": "completed",
  "answer": "The three largest files are…",
  "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",
  "steps": [
    { "index": 0, "title": "List a folder", "status": "success", "toolName": "list_directory", "toolArgs": { "path": "~/Downloads" } },
    { "index": 1, "title": "Respond to user", "status": "success", "toolName": "respond_to_user" }
  ],
  "usage": { "inputTokens": 5120, "outputTokens": 344, "generationMs": 8345, "ttftMs": 610, "tps": 41.2 }
}

answer is the assistant's closing message — the same text a person would read in the panel. steps is the ordered list of everything it actually did.

Watch the AI Workflows panel in Cephable while your request runs. The run appears there exactly as if you had typed it, because it is the same run.

5. Handle the three outcomes

Your client needs to distinguish three things, because two of them are HTTP 500-shaped and neither is a crash:

const response = await fetch(`${endpoint}/v1/runs`, { /* … */ });
const body = await response.json();

if (body.schemaVersion === 1) {
    // A real run happened. Trust body.status, not the HTTP code.
    // HTTP 200 → status 'completed'; HTTP 500 → 'failed' | 'canceled' | 'terminated'
    console.log(body.status, body.answer, body.errorCode);
} else {
    // No run happened: 400 (bad request / timeout), 401 (bad key), 409 (busy), 404 (wrong route)
    console.error(response.status, body.error.message);
}

A run that ends failed still returns a complete record with errorCode, steps, and usage — the diagnostics are the point. Checking for schemaVersion === 1 is the reliable way to tell "the agent ran and did not succeed" from "the request never started".

6. One run at a time

The app has a single inference slot, so the server refuses a second concurrent run with 409:

{ "error": { "message": "The on-device assistant is already running or preparing (executing-start)", "type": "conflict" } }

This includes runs the user started from the panel. Poll /health until busy is false and workflowStatus is idle or terminated, or call POST /v1/automate/cancel to clear whatever is in flight. Both are safe while a run is active.

Next steps

Running Automate tasks — every option on /v1/runs, and how to read the response
Custom tools — give the agent your own tools
Samples — clone-and-run applications, plus copy-paste clients per language
Security model — before you ship an integration that holds this key

Or skip ahead and run something:

git clone https://github.com/Cephable/Cephable-Automate-Agent-Samples