# ooda — full documentation

> Cloud dev environments for teams — managed, sandboxed, and shareable.

ooda gives teams cloud dev environments with AI coding agents. Everyone gets their own sandboxed Linux VM — no local setup, no rogue deploys, no lost prototypes. Admins keep control of access, infrastructure, and what gets published.

## Getting started

### Prerequisites

- **Node.js 20+**

### Quick start

```
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

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

### Fields

- **name**: Human-readable project name (e.g. `"My Cool App"`). Shown in the dashboard instead of the project slug when set.
- **description**: Short description of what the project is. Shown in the dashboard alongside the name.
- **tools**: An object where each key is a tool name and the value is its configuration (usually `{}`). Tools are installed and configured when you run `/install-tools` or automatically when starting a project.
- **claude.model**: The AI model to use (defaults to `claude-sonnet-4-6`).

## 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

**[agentation](https://agentation.dev)** — Visual element selection for React apps. Adds a floating toolbar to your dev environment that lets you click on any element to select it, then ask the AI to modify it. Requires a React project. Built by [Benji Taylor](https://x.com/benjitaylor), [Dennis Jin](https://x.com/seldom) & [Alex Vanderzon](https://x.com/alexvanderzon).

More tools coming soon.

### Declaring tools

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

```json
{
  "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:

```json
{
  "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 to follow after installing...",
  "healthCheck": {
    "command": "ls node_modules/your-package",
    "description": "Verify the package is installed"
  }
}
```

### Fields

- **description** (required): Short description of what the tool does.
- **requirements**: Framework and dependency constraints. If the project doesn't meet these, the installer warns the user and skips the tool.
  - **requirements.frameworks**: Array of supported frameworks (e.g. `["react", "next"]`).
  - **requirements.dependencies**: Array of npm packages that must be present.
- **install**: Package installation details.
  - **install.ecosystem**: `"npm"`, `"gem"`, or `"pip"`.
  - **install.package**: The package name to install.
  - **install.version**: Optional version constraint.
- **mcp**: MCP server configuration. Use `"stdio"` transport for local servers or `"http"` for remote ones.
  - **mcp.transport**: `"stdio"` or `"http"`.
  - **mcp.command** (stdio): The command to run.
  - **mcp.args** (stdio): Array of arguments.
  - **mcp.url** (http): The server URL.
- **setupInstructions**: Markdown instructions that the AI agent follows after installing. Use this for code changes like adding imports, inserting components, or modifying config files.
- **healthCheck**: Verification after setup.
  - **healthCheck.command**: Shell command to run (exit 0 = pass).
  - **healthCheck.description**: Human-readable description of what to look for.

### 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.

### 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                         # Interactive menu + dashboard
ooda-cli connect <name>              # Direct connect to a running project
ooda-cli list                        # List all your projects
```

- **npx ooda-cli**: Launch the interactive project manager. Lists your existing projects and lets you create new ones, deploy local folders, or connect to running projects.
- **ooda-cli connect <name>**: Connect directly to a running project by name. Opens an AI coding session in your terminal. Useful for opening additional sessions to the same project.
- **ooda-cli list**: List all your projects and their current status.

## Auth options

- **Email + OAuth**: Sign in with your email on first run
- **Organization**: Join your team's org automatically via email invite
- **Corporate LLM gateway**: Admins configure once, members inherit automatically

## More info

- Website: https://ooda.run
- Docs: https://ooda.run/docs
- npm: https://www.npmjs.com/package/ooda-cli