# Quick Start

> Enable the Automate HTTP Server in the Cephable desktop app, copy your access key, and run your first on-device Automate task over HTTP.

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

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

1. In Cephable, open **Extensions**.
2. Under **Cephable features → Build & Extend**, find **Automate HTTP Server**.
3. Enable it from the card.
4. 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:

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

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

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

```jsonc
{
  "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](/docs/automate-http-server/troubleshooting).

---

## 4. Run your first task

```bash
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:

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

```javascript
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`:

```jsonc
{ "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](/docs/automate-http-server/runs) — every option on `/v1/runs`, and how to read the response
- [Custom tools](/docs/automate-http-server/custom-tools) — give the agent your own tools
- [Samples](/docs/automate-http-server/samples) — clone-and-run applications, plus copy-paste clients per language
- [Security model](/docs/automate-http-server/security) — before you ship an integration that holds this key

Or skip ahead and run something:

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