Documentation

Getting started

ooda lets your team publish prototypes and tools to the web safely, from any agent — with optional cloud dev environments when you need them. One command signs you in and gets you building or publishing, no local setup required.

Prerequisites

• Node.js 20+

Quick start

Install it globally and run ooda:

$ npm install -g @oodarun/cli
$ ooda

The CLI tells you when a newer version is available, so a global install won't go stale. You can also run it without installing via npx @oodarun/cli@latest.

The first time you run it, you'll be asked to sign in with your email. If you're part of an organization, you'll be connected to your team's shared environment automatically. Select a project or create a new one — ooda handles the rest.

ooda.json

ooda.json is the project configuration file. Place it in your project root to declare tools, set the AI model, and configure other options.

Example

{
  "name": "My Cool App",
  "description": "A React dashboard for analytics",
  "tools": {
    "agentation": {}
  },
  "claude": {
    "model": "claude-sonnet-4-6"
  }
}

Fields

Tools

ooda has a tool system that lets you add MCP servers and other integrations to your project. Tools are declared in ooda.json and installed automatically.

How it works

When you declare a tool in ooda.json and run /install-tools (or start a project, which runs it automatically), ooda:

1. Looks up the tool in its built-in registry
2. Checks that your project meets the tool's requirements (framework, dependencies)
3. Installs the npm package
4. Registers the MCP server with the AI agent
5. Follows the tool's setup instructions (adding components, modifying config files)
6. Runs health checks to verify everything works

Built-in tools

More tools coming soon.

Declaring tools

Add a tool to your project by including it in the tools object:

{
  "tools": {
    "agentation": {}
  }
}

Building a tool

Third-party npm packages can self-describe as ooda tools by shipping an ooda-tool.json file in their package root. When a user declares your package name in their ooda.json, the installer discovers and uses your recipe automatically.

ooda-tool.json spec

The file follows the same shape as the built-in ToolRecipe type. All fields except description are optional:

{
  "description": "What your tool does",
  "requirements": {
    "frameworks": ["react", "next"],
    "dependencies": ["some-package"]
  },
  "install": {
    "ecosystem": "npm",
    "package": "your-package-name",
    "version": "^1.0.0"
  },
  "mcp": {
    "transport": "stdio",
    "command": "node",
    "args": ["./node_modules/your-package/mcp-server.js"]
  },
  "setupInstructions": "Markdown instructions for the AI agent...",
  "healthCheck": {
    "command": "ls node_modules/your-package",
    "description": "Verify the package is installed"
  }
}

Fields

How discovery works

When a tool name isn't in ooda's built-in registry, the installer checks node_modules/<package>/ooda-tool.json. If the file exists and is valid, it's used as the recipe. The name field is optional — it defaults to the package name.

Publishing

Publish your project to a gated, shareable URL with a single command. Just tell the AI to publish, or use the /publish command.

How it works

1. The AI builds your project with the correct base path for the publish URL
2. The build output is collected and uploaded
3. Your site is available at a {slug}-p.ooda.run URL, gated by your access policy

Every publish creates a new version. Previous versions are kept and accessible. Publishing is free with no limits on the number of projects.

Access control

Every site is gated. By default a site requires a team login; you can make any site public or password-protected, per site or as an org-wide default. Site passwords are encrypted at rest. Manage access from the dashboard or with ooda sites access.

Supported frameworks

Any framework that produces static output works — Vite, Astro, Next.js (static export), and more. The publish script automatically detects your build output directory (dist, build, out, etc.).

CLI commands

$ npx @oodarun/cli

$ ooda connect <name>

$ ooda list

$ ooda publish [path]

$ ooda sites [list|access|password|delete]

$ ooda secrets [set|list|rm|attach|detach]

$ ooda login  ·  ooda whoami  ·  ooda logout

Agent skill

Teach your coding agent (Claude Code, Cursor, etc.) how to use ooda — publishing static sites, managing sites, and authenticating — by installing the ooda agent skill. The agent can then publish and manage sites on its own, non-interactively.

# Global (all projects)
$ npx skills add toy-studio/ooda-skills -g

# Or per-project
$ npx skills add toy-studio/ooda-skills

Uses the skills CLI. Source and details: github.com/toy-studio/ooda-skills.