Documentation

Getting started

ooda gives teams cloud dev environments with AI coding agents. One command gets you a full sandboxed Linux VM ready to build in — no local setup required.

Prerequisites

• Node.js 20+

Quick start

Run the CLI and follow the prompts:

$ npx ooda-cli

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 permanent 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 shareable *.ooda.run URL

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

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 ooda-cli

$ ooda-cli connect <name>

$ ooda-cli list