# Samples

> Clone-and-run sample applications on GitHub, plus copy-paste Automate HTTP Server clients for Node.js, Python, .NET, shell and Swift — with endpoint discovery, readiness waiting, cancellation, and error handling.

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

---
There are two kinds of sample, and they are for different moments.

| | |
|---|---|
| **[Sample applications on GitHub](#sample-applications-on-github)** | Complete apps you clone and run. Use these to see what an integration looks like, or to demo it to someone. |
| **[Client code on these pages](#client-code-for-your-platform)** | A working client per language, to paste into a project you already have. |

---

## Sample applications on GitHub

**[github.com/Cephable/Cephable-Automate-Agent-Samples](https://github.com/Cephable/Cephable-Automate-Agent-Samples)** — MIT licensed, four applications, each runnable from a clean clone with one command.

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

### [Python + LangChain, with your own tools](https://github.com/Cephable/Cephable-Automate-Agent-Samples/tree/main/samples/python-langchain-tools)

A support-triage agent where your Python functions are the tools. The same job is implemented twice — once against the native `/v1/runs` park/resume loop with **no dependencies at all**, and once through LangChain's `ChatOpenAI` + `bind_tools`, with no Cephable-specific code in the agent loop.

**Stack:** Python 3.10+ · LangChain · standard library

### [WinUI + Windows AI](https://github.com/Cephable/Cephable-Automate-Agent-Samples/tree/main/samples/winui-windows-ai-agent)

A Windows desktop agent where three on-device AI systems cooperate and none touches a network: **Windows OCR** reads a pasted screenshot, **Phi Silica** summarizes and rewrites it, and **Cephable** decides what to do and chains the results. Includes the verified Windows App SDK 1.7 API shapes, which moved between SDK versions.

**Stack:** C# · WinUI 3 · Windows App SDK 1.7

### [Next.js + Vercel AI SDK + AI Elements](https://github.com/Cephable/Cephable-Automate-Agent-Samples/tree/main/samples/nextjs-vercel-ai-ui)

A chat UI built from Vercel's [AI Elements](https://ai-sdk.dev/elements) components, streaming Cephable's **real agent steps and tool calls** into the browser. Cephable does not stream tokens, but the park/resume loop is a real sequence of events, so the route handler writes each one into a `UIMessageStream` as it lands — as the SDK's own `tool-*` chunks, so a Cephable tool call renders through `<Tool>` with no translation layer. Two of its tools draw straight into the page.

**Stack:** TypeScript · Next.js · Vercel AI SDK · AI Elements

### [Public gateway](https://github.com/Cephable/Cephable-Automate-Agent-Samples/tree/main/samples/public-gateway)

A hardened reverse proxy for exposing one machine's server to remote callers: its own authentication, its own rate limits, per-caller run ownership, a queue for the single inference slot, and a request policy that **refuses** the parts of the API a remote caller must not have. Read this one before you answer "can we host it?"

**Stack:** TypeScript · Node · Fastify

### Try the samples without a Professional licence

The repo includes **[tools/fake-cephable](https://github.com/Cephable/Cephable-Automate-Agent-Samples/tree/main/tools/fake-cephable)** — a standard-library Python stand-in that speaks the protocol without running a model. It reproduces the things clients get wrong (bearer auth on every route, the park/resume loop, OpenAI tool-calling, a failed run as `HTTP 500` with a complete record) and logs what it received, so you can confirm your request was shaped correctly.

It is how the samples in that repo are tested, and it is enough to build an integration against before you have a licence. It listens on **4319** rather than 4317, so a real Cephable is unaffected — pin `CEPHABLE_ENDPOINT` to use it.

```bash
python tools/fake-cephable/fake_cephable.py --script incidents
```

---

## Client code for your platform

Each of the pages below is a working client you can paste into a project. They all implement the same five behaviors, because every robust integration needs them:

1. **Discover the endpoint** instead of hardcoding `4317` — Cephable moves ports when one is taken.
2. **Read the key from the environment**, never from source.
3. **Wait for readiness** on `/health` before starting a run, so a busy assistant does not turn into a `409`.
4. **Distinguish a failed run from a failed request** by checking `schemaVersion === 1`.
5. **Cancel on the error path**, so an abandoned run does not block the user's next one.

The Node and Python clients also include a `runWithTools` / `run_with_tools` helper that drives the park/resume loop for tools your own process executes — see [Custom tools](/docs/automate-http-server/custom-tools).

| Client | Good for |
|---|---|
| [Node.js / TypeScript](/docs/automate-http-server/samples/node) | CLI tools, Electron main process, build scripts, VS Code extensions |
| [Python](/docs/automate-http-server/samples/python) | Automation scripts, notebooks, eval harnesses, OpenAI-SDK clients |
| [.NET / C#](/docs/automate-http-server/samples/dotnet) | WPF, WinUI, and WinForms apps; Windows services; MAUI desktop |
| [Shell & PowerShell](/docs/automate-http-server/samples/shell) | `curl` one-liners, cron and Task Scheduler jobs, CI, Shortcuts and Automator |
| [Swift](/docs/automate-http-server/samples/swift) | Native macOS apps, menu-bar utilities, Automator and Shortcuts actions |

---

## Before you run any of them

```bash
# macOS / Linux
export CEPHABLE_AUTOMATE_KEY='paste-key-from-the-extension-detail-view'
```

```powershell
# Windows PowerShell
$env:CEPHABLE_AUTOMATE_KEY = 'paste-key-from-the-extension-detail-view'
```

Enable **Extensions → Cephable features → Build & Extend → Automate HTTP Server** in the Cephable desktop app first, and leave the app running. See the [Quick start](/docs/automate-http-server/quick-start).

## A note on browser JavaScript

None of these samples run in a web page, and there is no browser sample, because the server sends no CORS headers and has no `OPTIONS` handler — a `fetch` from an `http(s)://` origin fails preflight. Call the server from a native process, a Node or Electron main process, or your own local backend. (That is why the Next.js application sample proxies through a route handler.)