# Agent OS

Agent OS is a local-first studio for building AI-agent workflows by prompting and drag-and-drop. Codex API supplies the reasoning layer; Hermes or OpenClaw executes a workflow natively when the user explicitly enables trusted local execution.

## Product surface

- **Home:** prompt-to-workflow, Hermes and OpenClaw hero runtimes, and recent workflows.
- **Agent Builder:** one native visual canvas with add, drag, edit, delete, duplicate, save, prompt-refine, approval, Codex preview, and native run controls.
- **AI APIs:** server-side Codex API setup plus verified install/connect/test guides for ten gateway, hosted, local, and reference projects.
- **Agent control rooms:** install/test OpenClaw or Hermes, configure their local paths/profiles, preview a task with Codex, and turn that task into a workflow.

The former Setup, Workflows, Provider Router, Scheduler, Memory, Skills, and Self navigation groups are not part of the Agent OS interface. The older broad dashboard source remains unmounted; `src/main.tsx` renders only `AgentOSApp`.

## Runtime model

```text
User prompt
    │
    ▼
Codex API (OpenAI Responses API)
    ├── generates a strict JSON workflow
    ├── edits selected nodes or the full graph
    └── safely previews agent reasoning
             │
             ▼
Native Agent OS workflow graph
    ├── Hermes runtime
    └── OpenClaw runtime
```

Codex is not presented as a separate agent card and the Codex CLI is not used as the workflow brain. If no OpenAI API key is configured, Codex-powered operations return a clear setup error; they never return a fake successful workflow.

## Run locally

```bash
npm ci
npm run check
PORT=8090 npm start
```

Open [http://localhost:8090](http://localhost:8090). The health endpoint is [http://localhost:8090/api/health](http://localhost:8090/api/health).

For development with frontend and backend reload:

```bash
npm run dev
```

## Connect Codex API

1. Open **AI APIs**.
2. Add a user-owned OpenAI API key.
3. Keep `gpt-5.3-codex` or choose another Codex model supported by the Responses API.
4. Choose the reasoning effort and click **Save & test**.
5. The key is stored only in the server-side Agent OS runtime store and is never returned to the browser.

Equivalent environment variables:

```bash
OPENAI_API_KEY=...
AGENT_OS_CODEX_MODEL=gpt-5.3-codex
AGENT_OS_CODEX_REASONING_EFFORT=medium
AGENT_OS_OPENAI_BASE_URL=https://api.openai.com/v1
AGENT_OS_CODEX_TIMEOUT_MS=90000
```

## Build and run an agent

1. Describe the complete agent on Home.
2. Codex API creates a validated workflow with a start, understandable steps, and an end.
3. In the builder, choose **Hermes** or **OpenClaw** under **Run with**.
4. Drag nodes, edit a selected node, add/delete steps, or prompt Codex to modify the selected step or full workflow.
5. Use **Codex preview** to test reasoning without native tools.
6. Use **Enable & run Hermes/OpenClaw** to explicitly enable trusted local execution and run through the installed runtime.
7. Approval nodes pause and can be continued with **Approve & continue**.

## Clean first launch

Every new Agent OS installation starts with an empty Home workspace and one hidden blank builder graph. No demonstration workflows, simulated workflow counts, or prefilled run history are added. Open **Agent Builder** to add steps manually, or connect Codex API and describe the workflow you want Agent OS to build.

Workflows you create are normal local JSON files. You can save, reopen, edit, duplicate, dry-run, and delete them. Home statistics are calculated only from your saved graphs, while run counts and last-run states come only from your persisted runs.

Native execution is still protected by the server execution gate. It can also be enabled at startup with:

```bash
HERMES_AGENT_OS_ENABLE_EXEC=1
```

## Install the agent runtimes

Agent OS uses the official install paths:

```bash
# OpenClaw
npm install -g openclaw@latest
openclaw onboard --install-daemon

# Hermes Agent
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
hermes setup
```

Install buttons execute only when `HERMES_AGENT_OS_ENABLE_INSTALL=1`; otherwise Agent OS safely displays the exact command. OpenClaw native workflow calls use `openclaw agent --message <task> --thinking high`. Hermes remains connected to its local profile/runtime controls.

## AI API integration library

The AI APIs page contains install commands, start commands, Agent OS connection steps, base URL/model/key fields, health tests, licenses, source links, and caveats for:

| Project | Agent OS role | Default connection |
| --- | --- | --- |
| OmniRoute | Smart multi-provider gateway | `http://127.0.0.1:20128/v1` |
| CLIProxyAPI | Authorized CLI/OAuth compatibility gateway | `http://127.0.0.1:8317/v1` |
| Free LLM Gateway | Self-hosted provider/fallback gateway | `http://127.0.0.1:8080/v1` |
| GPT4Free | Experimental compatibility layer | `http://127.0.0.1:1337/v1` |
| New API | Managed multi-format model hub | `http://127.0.0.1:3000/v1` |
| Pollinations | Hosted multimodal tool/API | `https://gen.pollinations.ai` |
| Ollama | Local model runtime | `http://127.0.0.1:11434/v1` |
| LocalAI | Local multimodal OpenAI-compatible engine | `http://127.0.0.1:8080/v1` |
| llama.cpp | Lightweight local GGUF server | `http://127.0.0.1:8080/v1` |
| Awesome Free LLM APIs | Research directory, not an API | Not connectable |

Agent OS does not imply that upstream model usage is free, stable, or permitted by every account plan. Users must follow provider terms and keep local unauthenticated servers off untrusted networks.

## Important API endpoints

```text
GET  /api/agent-os/codex/status
POST /api/agent-os/codex/test
POST /api/agent-os/codex/preview
POST /api/agent-os/workflows/generate
POST /api/agent-os/workflows/refine

GET  /api/agent-os/api-integrations
POST /api/agent-os/api-integrations/:id/configure
POST /api/agent-os/api-integrations/:id/test

GET  /api/workflows
POST /api/workflows
PUT  /api/workflows/:id
POST /api/workflows/:id/run
POST /api/workflows/:id/runs/:runId/resume

GET  /api/modules
POST /api/modules/:id/test
POST /api/modules/:id/install
POST /api/connections/:id/configure
```

## Security and local state

- Runtime state remains under `~/.hermes-agent-os/` unless `HERMES_AGENT_OS_HOME` is changed.
- JSON config files are written with owner-only permissions.
- Secret values are redacted from API responses, logs, run proof, and tests.
- Public/VPS mode should set `HERMES_AGENT_OS_PUBLIC_MODE=1`, `HERMES_AGENT_OS_REQUIRE_AUTH=1`, and a strong `HERMES_AGENT_OS_ADMIN_TOKEN` behind HTTPS.
- Native agents can use tools and workspaces. Review their configuration before enabling native execution.

## Verification

```bash
npm run check
npm test
```

The runtime suite covers Codex structured-output generation, honest missing-key behavior, secret redaction, all ten API guide records, saved gateway health tests, visual workflow behavior, native OpenClaw invocation, approval/resume, installers, and the existing Agent OS backend modules.

## Docker

```bash
cp .env.example .env
docker compose up --build
```

The container persists Agent OS state in its configured volume. Native host CLIs are not automatically available inside the container; install runtimes in the image or connect compatible external services deliberately.
