Examples

Runnable examples showing how to use emberd, from basic API calls to wiring it into an OpenAI agent.

Each example lives in the examples/ directory of the repo and is fully self-contained. Clone the repo, start emberd, then run any example directly.

git clone https://github.com/hdprajwal/emberd
cd emberd
./bin/emberd   # daemon must be running before any example

01: basic-exec

The smallest complete program: create a sandbox, execute Python code, print the result, destroy the sandbox. Both a Python script and a curl/jq shell version.

02: shell-exec

Use the shell language pack to run POSIX shell commands inside a sandbox: uname, ps, df, and more. Both Python and curl versions.

03: state-persistence

Filesystem writes in one exec call survive into the next. Three sequential execs on one sandbox: generate data, compute statistics, print a report.

04: error-handling

How to handle syntax errors, runtime exceptions, non-zero exit codes, mixed stdout/stderr, and timeouts. A non-zero exit_code is never an HTTP error.

05: openai-agent

Wire emberd into a GPT-4o tool-calling agent. The model gets an execute_code tool backed by a real Firecracker microVM and reasons over the output.

Prerequisites

Examples 01-04 use only the Python standard library. Example 05 uses uv and manages its own dependencies via pyproject.toml.

The shell examples (run.sh) need curl and jq.

Override the daemon address with the EMBERD_ADDR environment variable (default 127.0.0.1:7777):

EMBERD_ADDR=127.0.0.1:8888 python examples/01-basic-exec/main.py