# OpenEng AI quickstart

> Sign in once, learn the Console in five minutes, publish your first config, and start the engine with your OpenEng key — then run it from the Web Console at app.openeng.app. As of September 25, 2026, the OpenEng AI services behind the Console and the engine aren't live yet.

Sign in once, learn the Console in five minutes, publish your first config, and start the engine with
your OpenEng key — then run it from the Web Console at
**[app.openeng.app](https://app.openeng.app)**.

> [!WARNING] Status on September 25, 2026: OpenEng AI isn't live yet
> The Console ([console.openeng.app](https://console.openeng.app)) and the Web Console
> ([app.openeng.app](https://app.openeng.app)) are published, but the services behind them aren't live
> yet: the OpenEng API doesn't answer OpenEng AI requests (your resources, configs, API keys, plan and
> engine registration), and the OpenEng Broker isn't online. Until they are, the Console can't load or
> save your work and no engine can register, whatever the plan. These pages describe OpenEng AI as it
> works once those services are live. The engineering apps don't depend on them.

> [!NOTE] What you need
> The **Free** plan includes signing in, the Console, and building and publishing configs. Starting
> the engine needs an OpenEng key and an active **Pro** plan; Pro launches in Q4 2026 and can't be
> purchased yet ([Plans & billing](account.md)). The engine is published for Linux x86_64 (on
> Windows, use WSL).

The steps, in order:

1. [Sign in](#1-sign-in) to the Console.
2. [Find your way around](#2-the-console-layout) the Console.
3. [Publish your first config](#5-your-first-publish): the engine serves nothing until you do.
4. [Create your OpenEng key](#4-create-your-openeng-key).
5. [Install and start the engine](#3-install-and-start-the-engine) with that key.
6. [Open the Web Console](#6-open-the-web-console), pick your engine and config, and start working.

*Figure: Your map of the console — Overview and Configs at the top of the left nav, then Building blocks · Connect · Govern · Deploy, the ⌘K header, and the Overview dashboard. Every Console guide in these docs (Building blocks, Connect, Govern & deploy) opens with this map pointing at the page it covers.*

## 1. Sign in

You have **one OpenEng account**, and every surface signs in through
**[auth.openeng.app](https://auth.openeng.app)** with Google — the Console, the Web Console, the
website, the billing site, and the five engineering apps all share it.

Open **[console.openeng.app](https://console.openeng.app)**. If you're not
signed in you land on the login page; **Continue with Google** completes the
sign-in and returns you to the page you were heading for.

> **Note:** There is no separate registration — your Google sign-in *is* your
> OpenEng account. AI pricing isn't public yet
> ([Plans & billing](account.md)).

## 2. The Console layout

The Console is the authoring side of OpenEng AI: you define things here, publish
a version, and the engine on your machine runs it. The shell has three
parts:

**The left nav** puts the config first and groups everything else by intent:

| Group | Pages |
|---|---|
| — | Overview — your working dashboard · Configs — build and publish configs |
| **Building blocks** | Library · Models · Agents · Skills · Templates · Loops · Schedulers |
| **Connect** | MCP servers · Cells · Connectors · Storage points |
| **Govern** | Token limits · Directories · Defaults · Gateway · Plugins · Roles · Human-in-the-Loop |
| **Deploy** | API keys · Sandboxes |
| **Account** | Plan & billing · Preferences · Sign out |

The sidebar collapses to icons with the **Collapse** button at its bottom
(remembered per browser). On phones it becomes a slide-in drawer behind the
menu button. The [Console tour](console.md) explains every page.

**The command palette** — press <kbd>⌘</kbd>+<kbd>K</kbd> (<kbd>Ctrl</kbd>+<kbd>K</kbd> on Linux and
Windows) anywhere, or click the *Search or jump to…* box in the header. It jumps to any page and
carries creation actions (*New model*, *New agent*, *Register cell deployment*, *New config*, …) plus
*Publish a config* and *Import a library*. <kbd>Esc</kbd> closes it.

**The Overview page** is a working dashboard: a first-run checklist you can dismiss (add a model,
create an agent, create and publish a config), your configs and whether they're published, counts of
your building blocks, your plan with its meters, recent activity, and the Deploy strip. There are no
usage/telemetry charts — the Console manages configuration and your fleet, not analytics.

> **Note:** Two habits the whole Console shares: the block editors **never save on
> their own** — every editor has a header **Save** button (disabled with the
> reason while the document is invalid; your in-progress edits mirror to a
> local browser draft with a "Restore unsaved draft?" prompt) — and every
> list row carries trailing **Edit**/**Delete** icon actions, with delete
> behind a confirmation. The one editor that saves by itself is the config builder, which keeps your
> draft as you go.

### Light & dark theme

**Account → Preferences** has a two-state Light/Dark switch (light is the
default). The choice is stored **to your account** — one switch renders
everywhere you sign in, on every device. Locally it also applies before first
paint, so there's no flash; after sign-in the server-stored value wins over
the local cache.

## 3. Publish your first config

The engine runs only what you publish, and until your account has a published config it refuses
every request. A new account starts with no config.

1. **Build** something — e.g. an agent: *Agents → New agent*, give it a name
   and a system prompt, and press **Save** in the editor header
   ([Agents](agents.md)). Add a model on the Models page too, or rely on the embedded defaults.
2. Open **Configs** ([guide](configs.md)). On a new account the page shows **Create your first
   configuration**: type a name, such as `workstation`, and press **Create**. The guided config
   builder opens.
3. Walk the steps in the rail. Most are optional: the functionalities in **Settings** start switched
   on, and model groups you leave unset in **Models** use the engine's embedded defaults. The
   component steps list only your own items, so the agent you just saved is there to tick.
4. On **Review & publish**, keep the suggested version (**1.0.0** for a first publish), add a note,
   check the changes and the validation list, and press **Publish v1.0.0**.

The version is published immediately. Everything you publish later works the same way: you bump the
version, and old versions stay available.

## 4. Create your OpenEng key

The engine authenticates with an **OpenEng key**, which is an API key you issue in the Console:

1. Open **Deploy → API keys** and press **Issue key**.
2. Give it a label (for example, the machine it will run on). Scopes are optional, and they're
   recorded but not enforced yet: every key has full account authority.
3. Copy the key. It's shown **exactly once**; the Console stores only a hash of it.

API keys need Pro: on the Free plan the API keys page explains what Pro unlocks instead of listing
keys, and on Pro **Issue key** is disabled, with the reason, once you reach your plan's key limit.
Each key runs one engine at a time ([API keys & sandboxes](api-keys-sandboxes.md)).

## 5. Install and start the engine

If you haven't installed the engine yet:

```bash
curl -fsSL https://openeng.app/engine/install.sh | bash
```

The installer puts the `openeng` binary in `~/.local/bin`, checks it against its published SHA-256
checksum when it can (it prints `checksum verified`; see
[Check a download yourself](install.md#verify-a-download)), and downloads
the default chat model. It's published for Linux x86_64; on Windows, run it inside WSL
([Install](install.md) covers platforms, options and uninstalling). The same command is on
[openeng.app/download](https://openeng.app/download).

Then start the engine with your key:

```bash
openeng serve --key=<your OpenEng key>

# or keep the key in your environment
export OPENENG_KEY=<your OpenEng key>
openeng serve
```

The engine registers the key with the OpenEng API, which checks it and your Pro plan. It then
applies your default config, downloads the models that config needs, and dials the OpenEng Broker.
It opens no port on your machine; the Web Console reaches it through the Broker. There is no
`--oauth` flag for this engine and no browser sign-in step. The [engine reference](engine.md) lists
every command, flag and environment variable, and what each startup message means.

> [!NOTE] One engine per key
> Each OpenEng key runs one engine at a time. Starting a second engine with
> the same key fails with `this key already runs an engine — stop it or generate a new key`; stop the
> first one, or use another key.

## 6. Open the Web Console

Open **[app.openeng.app](https://app.openeng.app)** and sign in with the same Google account as the
Console. The Web Console then walks you through three screens:

1. **Select an engine** — your account's engines, each marked online or with when it was last seen;
   pick one and press **Continue**. A newly started engine appears on its own. If none is connected,
   the screen shows the start command, `openeng serve`, to copy (it expects `OPENENG_KEY` in your
   environment).
2. **Pick a configuration + version** — only published configs are listed. With none published, you
   see the same "No configuration published" message the engine gives; publish one in the Console
   and the list updates on its own.
3. **Warming up your configuration** — the engine prepares everything the config needs, such as
   model downloads, with progress for each. Chat opens automatically when it's ready; **Skip to chat**
   lets you start while it finishes. If a required resource fails, the screen shows the failure with
   a **Retry** button.

If the config uses `${ENV}` placeholders, give them values on the Web Console's **Placeholder
values** screen for that config, or export them as environment variables where the engine runs; the
environment wins.

## How the engine picks up what you publish

The engine never authors configuration — it **resolves** what the Console
published, from `api.openeng.app`.

Three things worth knowing from day one:

- **You choose the version per session.** The Web Console's picker lists every published config and
  version, and refreshes while you pick, so a version you just published shows up within seconds. The
  engine fetches a version the first time a session uses it.
- **Versions are frozen** — a published version never changes, so a session keeps running the
  version it picked. To use a newer publish, pick the newer version. Each version also has a copyable
  pinned id, `<id>@<version>`, on its config's [version timeline](configs.md#the-version-timeline).
- **Requests that name no config** use the engine's default: the config given with `--default` or
  `OPENENG_DEFAULT_CONFIG`, otherwise the config you own named `default`, otherwise the first config
  you own ([The engine](engine.md#config-selection)).

## Plan notes

The **Free** plan includes signing in, the Console, authoring models, agents, templates, MCP servers
and cells, and building and publishing configs. **Pro** adds schedulers, API keys, sandboxes, storage points,
the Research and Device Use functionalities (Device Use also needs an engine build with the X11
device backend, which the published engine doesn't include yet), Roles, Human-in-the-Loop and an
included planning credit — and running the engine requires Pro. Pages gated to Pro explain what it unlocks, and the nav
wears a lock badge on Schedulers, Storage points, API keys and Sandboxes while the gate is closed. Pro
launches in Q4 2026; see [Plans & billing](account.md) for the current state of AI pricing. As of
September 25, 2026 the OpenEng AI services aren't live on any plan (see the status note at the top of
this page).

## Troubleshooting

**The Console says the platform API isn't reachable.** The banner reads *"The platform API isn't
reachable right now — your session is fine; data will load once the API is back."* The Console retries
automatically, and **Retry now** tries at once. Editors mirror your draft locally, so nothing is lost
while it's down.

**"Plan unverified" on a locked page or the Account page.** The plan couldn't
be confirmed (a transient network or sign-in hiccup), so the Console shows the
Free view defensively. Press **Refresh** next to the notice — a paying user is
never silently stranded.

**The engine won't start.** Read the line it printed: a missing key, a rejected key, a missing Pro
plan and a key that already runs an engine each have their own message
([engine troubleshooting](engine.md#troubleshooting)).

**The Web Console says "No configuration published".** Publish a config in the Console
([step 3](#5-your-first-publish)); the Web Console picks it up on its own.

**The engine doesn't run what I just published.** Check the three usual suspects: the same account
in the Console and the Web Console, the version picked for your session (pick the new one), and
whether the item is **disabled** (a "Not publishable" chip in its editor means the engine
deliberately skips it).

**Sign-in loops back to the login page.** Third-party-cookie or storage
blockers can break the redirect round-trip. Allow storage for
console.openeng.app and auth.openeng.app, then retry.