Docs Use Eco

Installation & usage

Try hosted Eco in five minutes, connect your app, or run locally.

On this page

Learn how to try hosted Eco, connect your app, or optionally run it locally.

A. Use hosted Eco in five minutes#

You need your own Orbio key (sk-orbio-…) and available Orbio credits. Eco does not create an account or issue a key. No installation is needed for the playground.

Open the Eco playground.
Paste your Orbio key into the session strip and choose Save key.
Choose auto/balanced and enter a message, such as “Explain HTTP caching in two sentences.”
Choose Preview to inspect the model decision, or Send to receive a reply. Use Stop to cancel an active stream.
Inspect the route panel. It shows the selected model and whether a classifier was used.

Your saved key stays in this browser's localStorage. Requests still send it over HTTPS to Eco and Orbio. Clear key removes the browser copy. See Privacy & keys.

Preview can spend classifier credits. Send also spends completion credits. Preview and Send route separately, so running both can use the classifier twice.

Connect your application#

For an OpenAI-compatible Chat Completions client, set two values in your application's environment:

eco@docs bash

export OPENAI_BASE_URL=https://api.orbioeco.sh/v1
export OPENAI_API_KEY='sk-orbio-…' # replace with your own Orbio key

These variable names are client settings. The key is an Orbio key, not an OpenAI key. Keep it out of committed files and public browser bundles.

With the JavaScript SDK installed, initialize the client and send a request:

eco@docs js

import OpenAI from "openai";

const eco = new OpenAI(); // reads the two environment variables above
const reply = await eco.chat.completions.create({
  model: "auto/balanced",
  messages: [
    { role: "user", content: "Explain HTTP caching in two sentences." },
  ],
});
console.log(reply.choices[0].message.content);

For a complete install-and-run example, see API quickstart. Use Chat Completions; Eco does not implement the Responses API.

Public URLs and a health check are in Hosting. You do not need to configure the hosted Eco server.

B. Developers and self-hosting (optional)#

This track is for builders working from an Eco repository checkout. Hosted users can skip it.

Run locally#

Use Node 22.12 or later; .nvmrc selects Node 24. The repository pins pnpm 9.15.0. If pnpm is missing, enable it through Corepack. If corepack is unavailable, install it with npm install --global corepack first. Run these commands from the repository root:

eco@docs bash

corepack enable pnpm
pnpm install --frozen-lockfile
cp .env.example .env
cp apps/web/.env.local.example apps/web/.env.local
pnpm --filter @eco/api dev

In a second terminal:

eco@docs bash

pnpm --filter @eco/web dev

Open http://localhost:3000/app. The API defaults to http://localhost:8787. Its health check needs no key:

eco@docs bash

curl --fail http://localhost:8787/v1/eco/health

Paste your Orbio key into the local playground. Keep it out of the server's .env file.

Local settings#

Setting	Where	Value or purpose
`NEXT_PUBLIC_ECO_API_BASE_URL`	`apps/web/.env.local`	`http://localhost:8787`, without `/v1`.
`PORT`	API environment	`8787` by default. Use another free port if needed.
`CORS_ORIGINS`	API environment	`http://localhost:3000` by default. Must match the browser's exact origin.
`ORBIO_BASE_URL`	API environment	Defaults to `https://api.orbio.so/api/v1`.

If 8787 is busy, start the API with:

eco@docs bash

PORT=8788 pnpm --filter @eco/api dev

Set the web API URL to http://localhost:8788 and restart the web development server. Keep the web on 3000 unless you also update CORS_ORIGINS. localhost and 127.0.0.1 are different browser origins.

Self-host overview#

Run the Eco web and API on your own hosting platform with HTTPS. Set NEXT_PUBLIC_ECO_API_BASE_URL to your API origin before building the web app. This public value is baked into the browser bundle. Set the API's CORS_ORIGINS to your web origin.

Configure the API's port and Orbio gateway URL for your environment. Users still supply their own keys per request; self-hosting does not require a shared server-side user key. Public API and SDK paths include /v1, while the web's API-origin setting does not.

Next: API quickstart or FAQ.