# ooda — full documentation

> Publish prototypes, tools, and sites to the web — safely, from any agent.

ooda lets teams publish prototypes, tools, and sites to the web safely, from any agent — login-protected by default and under your org. No rogue deploys, no lost prototypes. Admins keep control of access and what gets published.

## Getting started

### Quick start

Standalone (macOS and Linux, no Node.js needed):

```
curl -fsSL https://ooda.run/install | sh
ooda
```

npm (Node.js 20+, works on Windows):

```
npm install -g @oodarun/cli
ooda
```

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 join your team's org automatically. If you belong to several orgs, run `ooda orgs` to see them and `ooda switch <org-id>` to choose one. From a built site, run `ooda publish` to ship it to a private URL.

## ooda.json

`ooda.json` is the project configuration file. `ooda publish` reads the site's metadata from it, and writes the site's addresses back into it.

### Example

```json
{
  "name": "My Cool App",
  "description": "A React dashboard for analytics",
  "tags": ["dashboard", "react"],
  "color": "#0f766e"
}
```

### Fields

- **name**: Human-readable site name (e.g. `"My Cool App"`). Shown in the dashboard instead of the site slug when set.
- **description**: Short description of what the site is. Shown in the dashboard alongside the name.
- **tags**: Keyword tags for the published site, used for filtering and search.
- **color**: Brand colour (`"#rrggbb"`). The dashboard tints the site's card with it.
- **secrets**: A manifest of the env vars and secrets the site needs, so `ooda secrets check` can prompt for the missing ones.
- **slug**, **siteName**, **urls**: Written back by `ooda publish` — the resolved `{slug}.ooda.run` address and, when your org has short addresses, the `{siteName}.{org}.ooda.run` one. Keep them in the file so re-publishes stay on the same URL.

## Publishing

Publish a built static site to a permanent shareable URL with one command: `ooda publish`.

### How it works

1. Build your site (e.g. `npm run build`)
2. `ooda publish` detects the build output directory and uploads it
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.).

## Joining a team

On ooda, sites belong to a team (an organisation). If your team already uses ooda, join their team instead of creating a new one. Only a team admin can add you.

Ask an admin of your team to add you from the Team page in the dashboard:

- **Email invite**: the admin enters your email address. You get an email with a link to create your account. Sign up with that same address. The invite expires after 7 days.
- **Join link**: the admin shares a link. Anyone who opens it can join the team, so the admin can limit how many times it works or revoke it.

**If you already have an account**: one account can belong to several teams. Open the Account page in the dashboard to accept a pending email invite (verify your email address first), or open a join link while you are signed in. Run `ooda orgs` to list your teams and `ooda switch <org-id>` to choose the one the CLI publishes to.

**Waitlist invites**: a waitlist invite creates a new team with you as its admin. To join an existing team, do not use it. Ask that team's admin for an invite.

## CLI commands

```
ooda publish [path]                      # Publish a built static site to {slug}.ooda.run
ooda sites [list|access|password|delete] # Manage published sites
ooda secrets [set|list|rm]               # Env vars & secrets for your sites
ooda login | whoami | logout             # Sign in (email code), check session, sign out
ooda orgs | switch <org-id>              # List your orgs, choose the current one
```

- **ooda publish [path]**: Publish an already-built static site to a shareable {slug}.ooda.run URL. Set `--title` and `--description` (and `--tags a,b,c`) so it reads well in the dashboard and is searchable; use `--message` / `-m` to note what changed in a publish. Non-interactive; `--json` supported.
- **ooda sites …**: List/manage published sites — set access (public/password/login), reveal a password, or unpublish.
- **ooda secrets …**: Manage env vars & secrets for your published sites. `--env` values reach a site's page as `window.__OODA_ENV__.KEY`; true secrets never reach the browser. The CLI never prints a value (no reveal); an admin reveals in the dashboard.
- **ooda login / whoami / logout**: Email-code sign-in (`--email`/`--code` for agents/CI), check the current session, or sign out.
- **ooda orgs / switch <org-id>**: List the orgs your account belongs to, and choose the one that later commands act on.

## Agent skill

Teach your coding agent (Claude Code, Cursor, etc.) to use ooda. No install is needed — the skill is hosted at https://ooda.run/skill.md. Tell the agent:

```
Fetch https://ooda.run/skill.md and follow its instructions.
```

To install it into the agent's skills directory instead (so it loads automatically in future sessions):

```
npx skills add toy-studio/ooda-skills -g     # global
npx skills add toy-studio/ooda-skills        # per-project
```

It covers authentication, publishing static sites, and managing published sites — so an agent can publish and manage sites non-interactively. Source: https://github.com/toy-studio/ooda-skills

## Cloud agents

Cloud agents, such as Claude Code on the web, Codex, ChatGPT and Claude.ai, run their code in a sandbox, and most sandboxes block ooda by default. Set up the network once for each environment:

- **Claude Code on the web:** in the environment settings, set **Network access** to **Custom**. Add `ooda.run` and `*.ooda.run` to **Allowed domains**, and select **Also include default list of common package managers**.
- **Codex:** in the cloud environment settings, set **Agent internet access** to **On**. Choose the **Common dependencies** allowlist and add `ooda.run` and `api.ooda.run`. Keep all HTTP methods allowed, because a publish uses `POST`. Codex runs a task without you, so send the login code as a follow-up message.
- **ChatGPT:** no setup is necessary. If a request fails, check **Settings → Data controls → Work network access**.
- **Claude.ai:** in **Settings → Capabilities → Code execution and file creation**, turn on **Allow network egress**. If the allowlist is not **All domains**, add `ooda.run` and `*.ooda.run`. On Team and Enterprise plans, an admin controls this setting.

The sandbox does not keep a session, so the agent signs in with an email code each time. The agent requests the code, you paste it into the chat, and the agent verifies it:

```
npm install -g @oodarun/cli
ooda login --email you@example.com --json
ooda login --email you@example.com --code 123456 --json
ooda publish ./dist --json
```

A new code cancels the earlier codes, so paste the code from the latest email. If your account is in several orgs, the CLI selects one and lists the others. Add `--org <org-id>` to the verify step to choose, or run `ooda switch <org-id>` after it.

In a sandbox, install the CLI with npm, not with the standalone installer. The sandboxes include Node.js and allow the npm registry, and the Node CLI uses the proxy that `HTTPS_PROXY` names. The standalone binary does not need Node.js, but some sandbox proxies do not work with it. If an older CLI fails with `fetch failed`, update it, or set `NODE_USE_ENV_PROXY=1`.

## Auth options

- **Email code**: `ooda login` emails you a sign-in code (`--email`/`--code` for agents and CI)
- **Organization**: Join your team's org automatically via email invite
- **Several orgs**: Accept another org's invite or join link in the dashboard, then switch between orgs there or with `ooda switch`

## More info

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