Agent OS tutorial by Sriram

Agent OS Setup and Configuration Guide

Download Agent-OS.zip, open the clean empty workspace, then build your own workflow with the visual builder, Codex, or Claude Code.

  • Practical setup
  • Beginner-readable
  • Business workflow focus
Work with Sriram

Build automation around how your team actually works.

Send your requirement and get a tailored AI automation blueprint built for your business. No fluff, just what actually works.

Get this built for my business

Download package

Start with the zip file, then follow the safe install path.

Agent OS is a local-first studio for building AI-agent workflows. The package includes the dashboard, Express backend API, workflow routes, test suite, and project documentation. A fresh install contains no demonstration workflows or simulated run history.

Download Agent-OS.zip

File: Agent-OS.zip

What is Agent OS?

A local-first command center for AI-agent workflows.

Agent OS lets you describe an agent, build a visual workflow, connect your preferred model provider, and verify each step from one local dashboard. Codex can supply the reasoning layer, while Hermes or OpenClaw can execute trusted workflows only after you explicitly enable local execution.

BuildTurn a plain-language idea into an inspectable workflow graph and agent configuration.
ConnectUse the AI APIs area to configure OpenAI-compatible providers, local runtimes, and optional gateways.
Run safelyStart in dry-run mode with execution and install flags disabled, then enable trusted local actions deliberately.

What the Agent OS package contains

DashboardA local interface for workflow status, provider connections, logs, and agent configuration.
BackendAn Express API that serves the dashboard and exposes health, workflow, provider, and runtime checks.
State storeLocal data under ~/.hermes-agent-os; keep this directory private on your machine or server.
DocumentationREADME.md, SETUP-GUIDE.md, environment examples, and test commands for repeatable setup.
Clean workspaceHome starts with no workflow cards. Open the hidden blank builder, add your own steps, name the workflow, and save it.
Safety defaultsNo API keys or private machine data are included in the shared package; execution stays disabled until you choose otherwise.

1. Run a local smoke test

Use the local smoke test before sending the package to a server. It proves the zip extracts, dependencies install, checks pass, and the dashboard starts on a normal machine.

cd ~/Desktop
unzip "Agent-OS.zip" -d Agent-OS
cd Agent-OS
npm ci
npm run check
npm test
PORT=8090 npm start

Open http://localhost:8090, then verify the backend from a second terminal:

curl http://localhost:8090/api/health
curl http://localhost:8090/api/agent-os/codex/status
curl http://localhost:8090/api/workflows

On a fresh install, Home should say No agents built yet. Select Open blank builder, add steps, name the workflow, and save it. The new workflow should then appear on Home.

2. Keep the first run safe

Create .env from .env.example. If a real .env already exists, back it up before changing anything.

PORT=8090
HERMES_AGENT_OS_HOME=~/.hermes-agent-os
HERMES_AGENT_OS_ENABLE_EXEC=0
HERMES_AGENT_OS_ENABLE_INSTALL=0
HERMES_AGENT_OS_PUBLIC_MODE=0
OLLAMA_HOST=http://127.0.0.1:11434

Leave provider keys blank until the user supplies them. Do not paste API keys into screenshots, docs, prompts, or committed files.

3. Configure it with Codex or Claude Code

Choose one coding agent to help inspect, configure, and verify the project. Codex or Claude Code does not replace the Agent OS runtime; it works alongside the local dashboard.

Codex CLIUse the OpenAI coding agent to inspect the repository, edit configuration, and run the smoke-test commands with your approval.
Claude CodeUse the Anthropic coding agent for the same install and verification flow when Claude is your preferred coding assistant.

Codex CLI

npm install -g @openai/codex
cd ~/Desktop/Agent-OS
codex --login
codex

Claude Code

npm install -g @anthropic-ai/claude-code
cd ~/Desktop/Agent-OS
claude

When the CLI opens, ask it to read README.md and SETUP-GUIDE.md first. Keep execution and install flags set to 0 until you trust the machine and the workflow.

4. Host it on a VPS

For production, use Ubuntu 22.04 or 24.04, Node.js 20+, Nginx, HTTPS, and a dedicated service user. Keep app ports internal only.

apt update
apt install -y curl ca-certificates unzip nginx git
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs
mkdir -p /opt/agent-os
unzip "/root/Agent-OS.zip" -d /opt/agent-os
cd /opt/agent-os
npm ci
npm run check
npm test

Run the app behind systemd, proxy public traffic through Nginx to 127.0.0.1:8090, then install HTTPS with Certbot.

5. Configure providers only when needed

OpenRouterSet OPENROUTER_API_KEY, restart Agent OS, then test the OpenRouter provider card.
MiniMaxSet MINIMAX_API_KEY, restart Agent OS, then configure the MiniMax provider if you use it.
OllamaInstall Ollama separately, keep it on 127.0.0.1:11434, and never expose it publicly.
Claude CodeInstall @anthropic-ai/claude-code only if you want Claude Code CLI workflows.
CodexInstall @openai/codex only if you want Codex CLI/OpenAI workflows on that machine.

6. Use the real Agent Builder only after credentials are ready

The builder source is included, but do not call the real Agent Builder fully working until Convex and Clerk are configured and the API proves it.

NEXT_PUBLIC_CONVEX_URL=
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=
CLERK_SECRET_KEY=
CLERK_JWT_ISSUER_DOMAIN=
FIRECRAWL_API_KEY=
npm run builder:install
npm run builder:start
curl http://127.0.0.1:8090/api/builder/status

7. Paste this into Claude Code or Codex

After downloading the zip, paste this prompt into Claude Code, Codex, or another coding agent on the same machine.

You are helping me install and verify Agent OS from a local zip package.

Zip file:
Agent-OS.zip

Goal:
Install Agent OS locally, configure the safe first-run environment, verify the dashboard, and leave me with exact URLs and commands.

Important rules:
- Do not upload or expose any API keys.
- Do not invent connected status. Verify with the app APIs.
- A fresh install should return only the hidden blank builder workflow; do not add demonstration workflows.
- Keep execution disabled by default:
  HERMES_AGENT_OS_ENABLE_EXEC=0
  HERMES_AGENT_OS_ENABLE_INSTALL=0
- If API keys are missing, leave fields blank and explain where I should add them.
- Do not run destructive commands.
- Do not overwrite an existing `.env` without backing it up.
- Do not expose Ollama publicly.
- Do not claim the real Agent Builder is fully running unless Convex and Clerk are configured and `/api/builder/status` proves it.

Tasks:

1. Locate the zip file.
   If it is on Desktop, use:
   ~/Desktop/Agent-OS.zip

2. Create an install folder:
   ~/Desktop/Agent-OS

3. Unzip the package there.

4. Find the folder containing `package.json`.
   Use that folder as the app root.

5. Inspect:
   - package.json
   - .env.example
   - README.md
   - SETUP-GUIDE.md or HERMES-AGENT-OS-TUTORIAL.md if present

6. Install dependencies and run the project checks:
   npm ci
   npm run check
   npm test

7. Create `.env` from `.env.example` if `.env` does not exist.
   If `.env` exists, copy it to `.env.backup-YYYYMMDD-HHMMSS` first.

8. Configure safe local defaults in `.env`:
   PORT=8090
   HERMES_AGENT_OS_HOME=~/.hermes-agent-os
   HERMES_AGENT_OS_ENABLE_EXEC=0
   HERMES_AGENT_OS_ENABLE_INSTALL=0
   HERMES_AGENT_OS_PUBLIC_MODE=0
   OLLAMA_HOST=http://127.0.0.1:11434

9. Leave these blank unless I provide keys:
   OPENROUTER_API_KEY=
   MINIMAX_API_KEY=
   ANTHROPIC_API_KEY=
   OPENAI_API_KEY=
   GEMINI_API_KEY=
   FIRECRAWL_API_KEY=
   NEXT_PUBLIC_CONVEX_URL=
   NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=
   CLERK_SECRET_KEY=
   CLERK_JWT_ISSUER_DOMAIN=

10. Start the app:
    PORT=8090 npm start

11. Verify endpoints:
    curl http://localhost:8090/api/health
    curl http://localhost:8090/api/agent-os/codex/status
    curl http://localhost:8090/api/workflows

12. Confirm dashboard URL:
    http://localhost:8090

13. Confirm module behavior:
    - The dashboard should load and the health endpoint should return a real response.
    - Provider modules should be connected only if keys/endpoints are configured.
    - Hermes or OpenClaw execution should remain disabled unless I explicitly enable it.

14. If Ollama is installed, verify:
    curl http://127.0.0.1:11434/api/tags
    Keep Ollama bound to localhost.

15. Final response must include:
    - App root path.
    - Dashboard URL.
    - Health endpoint result.
    - Test/build result.
    - Which providers are connected.
    - Which providers need configuration.
    - Where `.env` is located.
    - Next steps for Codex, Claude Code, Ollama, and any optional runtime.

Final verification checklist

  • The zip extracts cleanly and the folder containing package.json is the app root.
  • npm ci, npm run check, and npm test complete.
  • /api/health, /api/agent-os/codex/status, and /api/workflows return real responses.
  • A fresh Home screen has no demonstration workflow cards and offers Open blank builder.
  • A workflow created from the blank builder can be saved, reopened from Home, and dry-run.
  • Codex or Claude Code starts in the Agent-OS folder and reads the setup docs.
  • Provider modules are connected only when their keys or local endpoints are configured.
  • HERMES_AGENT_OS_ENABLE_EXEC and HERMES_AGENT_OS_ENABLE_INSTALL stay 0 until the machine is trusted.
  • Ollama and app port 8090 are not exposed directly to the public internet.

Troubleshooting

  • For app logs on VPS, run journalctl -u agent-os -f.
  • For builder logs, run journalctl -u agent-os-builder -f.
  • If port 8090 is busy, run lsof -ti:8090 and change the port intentionally.
  • If Ollama fails, run systemctl status ollama and curl http://127.0.0.1:11434/api/tags.
  • If the builder does not render, check Convex, Clerk, npm run builder:install, and /api/builder/status.
Sriram Varadarajan Sriram VaradarajanReplies personally

Want this connected to a real business workflow?

The guide gets Agent OS running safely. The next step is deciding which provider keys and agent workflows should actually be wired for your business.

Map my automation