EmbedThis

Appearance

App Scaffold ​

The Ioto agent distribution includes a complete app scaffold that gives AI coding agents everything they need to start building immediately:

  • Pre-installed Ioto agent release — Ready to build and run with a single make command.
  • Full AI context — Documentation for all APIs, data structures, and architectural decisions.
  • 17 AI skills — Guided workflows for code audit, cross-compile, database, debugging, device UI, HTTP, JSON, MQTT, OpenAI integration, REST APIs, runtime, TLS configuration, UI spec, unit testing, WebSockets, and more.
  • Makefiles and project build files — Multi-platform build support for immediate development.

Directory Structure ​

myapp/
├── src/                        # Application source code
├── Makefile                    # Build file
├── ioto/                       # Ioto agent distribution
│   ├── include/                # API headers (ioto.h)
│   ├── build/bin/              # Built library (libioto.a)
│   ├── AI/                     # AI context documentation
│   │   ├── context/            # Per-module API guides
│   │   └── designs/            # Architecture documentation
│   └── .claude/skills/         # AI guided workflows
├── state/
│   ├── config/                 # Runtime configuration (JSON5)
│   ├── certs/                  # TLS certificates
│   └── db/                     # Database files
└── projects/                   # IDE project files

The key directories are:

  • ioto/include/ — Contains ioto.h and all dependent headers. Include this path when compiling.
  • ioto/build/bin/ — Contains the built libioto.a static library (or ioto.lib on Windows) and utility tools.
  • state/config/ — Contains the runtime configuration files that Ioto reads at startup. The state/ directory is also used at runtime for certificates, database files and logs.

Creating a New App ​

  1. Create the app directory and install the Ioto agent:
bash
mkdir myapp
cd myapp
tar xf ioto-VERSION.tar.gz && mv ioto-* ioto
  1. Copy configuration from a sample app template:
bash
mkdir -p src state/config
cp ioto/apps/http/*.json5 state/config/

  1. Configure services by editing ioto/include/config.h — set SERVICES_* defines to enable/disable services.

  2. Build the Ioto library:

bash
make -C ioto

  1. Create src/myapp.c with ioStart() and ioStop() entry points.

  2. Create a Makefile and build your application.

Integration Models ​

Own Main (Full Control) ​

Embed Ioto in your own main program:

c
#include "ioto.h"

int main()
{
    ioStartRuntime(1);
    ioRun(NULL);
    ioStopRuntime();
    return 0;
}

int ioStart(void)
{
    rInfo("app", "Hello World");
    return 0;
}

void ioStop(void) {}

Ioto-Managed Main (Simpler) ​

Use the Ioto command program and provide ioStart and ioStop functions:

c
#include "ioto.h"

PUBLIC int ioStart(void)
{
    rInfo("app", "Hello World");
    return 0;
}

PUBLIC void ioStop(void) {}

Spawning Long-Running Tasks ​

ioStart must not block. For long-running tasks, spawn a fiber:

c
int ioStart(void)
{
    rSpawnFiber("myFiber", (RFiberProc) longRunningTask, NULL);
    return 0;
}

Example Makefile ​

makefile
NAME   := myapp
LIB    := ioto/build/bin/libioto.a -lssl -lcrypto
CFLAGS := -Iioto/include $(LIB)

all: build

build: library $(NAME)

library:
	@make -C ioto

$(NAME): src/$(NAME).c ioto/build/bin/libioto.a
	cc -o $(NAME) src/$(NAME).c $(CFLAGS)

run:
	./$(NAME)

Next Steps ​

  • AI Context — Learn about the documentation provided to AI agents
  • AI Skills — Browse the available guided workflows
  • Embedding — Detailed guide to embedding Ioto in your application