Get Started with AI Agents: Hello World in Server Mode

CLI mode runs once and exits. Server mode starts your agent as an HTTP server — any application, script, or webhook can trigger it by sending a POST request. Same YAML, same config, completely different interface.

CLI Mode vs Server Mode

If you followed the CLI mode hello world, you ran the agent once from a terminal and it exited when done. That is perfect for scheduled jobs, one-off automation, and testing.

Server mode is for when you need to trigger your AI agent from another system — a web app, a mobile backend, a CI pipeline, a webhook, or a simple curl call. The runtime starts up once and stays running, ready to accept requests.

What You Need

• Node.js 18+ installed (for the npx approach), or the OE Runtime binary downloaded from openenthrium.com/runtime
• An API key from OpenAI, Anthropic, or any supported LLM provider
• curl or any HTTP client to test the endpoint

Create the Skill Files

Create a folder called hello-world/ and add these files. This is identical to the CLI mode example, now using the SKILL.md format:

---
name: hello-world
description: Greets you and tells you today's date. Use to verify OE Runtime is working correctly or as a starting template.
license: Apache-2.0
metadata:
  author: Open Enthrium
  version: "1.0"
---

You are a helpful assistant.

## Step 1: Greet
Say hello and today's date.

name: Hello World
description: Greets you and tells you today's date
skills:
  - path: ./
    trigger_type: auto

Create oe-config.json with server enabled

This time, add a server section to oe-config.json and set enabled to true:

{
  "llm": {
    "provider": "openai",
    "model": "gpt-4o",
    "apiKey": "sk-..."
  },
  "server": {
    "enabled": true,
    "port": 3333,
    "apiKey": "your-secret"
  }
}

The apiKey under server is a token you choose — it protects your endpoint so only callers that include it can trigger the agent. Set it to anything you like; you will pass it as the x-api-key header in every request.

Start the Server

Run from the parent folder (one level above hello-world/) — the server section in the config starts it automatically:

npx -y @openenthrium/oe-runtime@latest ./hello-world

Or use the --serve flag explicitly:

npx -y @openenthrium/oe-runtime@latest ./hello-world --serve

You will see the server start up:

The runtime is now listening. It stays running until you stop it with Ctrl+C.

Call It via HTTP

Three endpoints are available:

First, confirm it is alive:

curl http://localhost:3333/health \
  -H "x-api-key: your-secret"

Now trigger the hello world agent from a file:

curl -X POST http://localhost:3333/run-file \
  -H "x-api-key: your-secret" \
  -H "Content-Type: application/json" \
  -d '{"file":"agent.yaml","params":{}}'

The response comes back as JSON:

{
  "success": true,
  "output": "Hello! Today's date is August 11, 2026.",
  "duration_ms": 1823
}

You can also send inline YAML directly in the request body — useful for dynamically generated agents:

curl -X POST http://localhost:3333/run \
  -H "x-api-key: your-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "yaml": "name: Hi\nsteps:\n  - name: Greet\n    content: Say hi!",
    "params": {}
  }'

What Just Happened

The runtime loaded your agent and config on startup, then waited. When your curl request arrived, it executed the agent steps, called the LLM, and returned the result as a JSON response — all within the same running process. The server is ready for the next request immediately.

From here, any language that can make an HTTP POST can trigger your agent. Python, JavaScript, Go, a webhook handler, a GitHub Action — all of them work exactly the same way.

When to Use Server Mode

• Web apps — trigger an agent from a button click or form submission in your frontend
• Webhooks — have Slack, GitHub, or any service fire the agent when an event happens
• Internal tools — let your team call agents from a simple dashboard without CLI access
• Multi-agent orchestration — one agent can call another via HTTP as part of a larger workflow
• ISVs and integrators — embed OE Runtime as a microservice inside your own product