Skip to content

README.md

Latest commit

 

History

History
398 lines (275 loc) · 11.2 KB

README.md

File metadata and controls

398 lines (275 loc) · 11.2 KB
Raw

OpenViking Web Studio

English / 中文

Web Studio is the React/Vite frontend workspace for OpenViking. It is a static single page application for resource management, retrieval, bot-backed sessions, and operational diagnostics.

Web Studio does not embed OpenViking storage, indexing, retrieval, task queues, or VikingBot runtime. It must connect to a running OpenViking Server.

Runtime Contract

Default local server URL:

http://127.0.0.1:1933

The sessions UI requires VikingBot endpoints proxied by OpenViking Server:

GET  /bot/v1/health
POST /bot/v1/chat
POST /bot/v1/chat/stream
POST /bot/v1/feedback

For local development and deployment, start OpenViking Server with bot support:

openviking-server --with-bot

Without --with-bot, core APIs such as resources, search, tasks, and system status may still work, but /bot/v1/* returns 503; the sessions page cannot provide real chat behavior.

Quick Start

1. Start the Server

From the repository root:

uv pip install -e ".[bot,dev]"
openviking-server init
openviking-server doctor
openviking-server --with-bot

Or from the published package:

pip install "openviking[bot]"
openviking-server init
openviking-server doctor
openviking-server --with-bot

Check the required server surface:

curl http://127.0.0.1:1933/health
curl http://127.0.0.1:1933/ready
curl http://127.0.0.1:1933/bot/v1/health

2. Start Web Studio

Use Node.js 22.x for local development, builds, and tests, matching the Studio build workflow.

With the current Vitest/jsdom versions, Node.js 26 can cause localStorage errors during tests. If this occurs, switch to Node.js 22.x and run npm ci && npm test in web-studio/.

cd web-studio
npm install
npm run dev

Open:

http://127.0.0.1:3000

To override the initial server URL:

VITE_OV_BASE_URL=http://127.0.0.1:1933 npm run dev

The connection dialog can still override the server URL, API key, account ID, and user ID at runtime.

Filesystem Page

Open /filesystem to browse and preview context, run terminal commands, or use the Agent panel. When Studio is served under /studio, the URL is /studio/filesystem.

The former /playground route redirects to /filesystem, preserving the selected file, directory, panel, session, and URL fragment. Existing browser-stored layout and history remain available.

Connection and Auth

Application code should use the adapter under src/lib/ov-client instead of importing from src/gen/ov-client directly. The adapter centralizes base URL handling, auth headers, telemetry defaults, and error normalization.

Browser storage:

Value Storage Key
API key sessionStorage ov_console_api_key
Base URL, account ID, user ID localStorage ov_console_connection

Request headers injected by the adapter:

  • X-API-Key
  • X-OpenViking-Account
  • X-OpenViking-User

For production or multi-tenant deployments, configure a real server.root_api_key or user key in OpenViking Server and enter the matching connection settings in Web Studio.

Commands

Command Purpose
npm run dev Start the Vite dev server on port 3000.
npm run build Build the static production bundle into dist/.
npm run preview Preview the built dist/ bundle locally.
npm run lint Run ESLint for the current business-code scope.
npm run format Check formatting with Prettier.
npm run check Run Prettier write mode and ESLint autofix.
npm run test Run Vitest.
npm run gen-server-client Regenerate src/gen/ov-client from server OpenAPI.

Generated OpenAPI Client

Generated code lives under:

src/gen/ov-client

Do not edit generated files by hand. Regenerate them from the target OpenViking Server version:

openviking-server --with-bot
cd web-studio
npm run gen-server-client

The generation script currently reads:

http://127.0.0.1:1933/openapi.json

It formats the OpenAPI document, normalizes operation IDs, and runs @hey-api/openapi-ts.

Project Layout

src/routes/              TanStack Router routes
src/routes/<page>/       Top-level page modules
src/routes/<page>/*.ts   Explicit public feature entry points for cross-route reuse
src/routes/<page>/-*     Page-private components, hooks, schemas, and helpers
src/components/ui/       Shared base UI primitives
src/components/          Shared app components
src/hooks/               Shared React hooks
src/lib/ov-client/       Runtime OpenViking client adapter
src/gen/ov-client/       Generated OpenAPI client
src/i18n/locales/        en and zh-CN translation resources
src/styles.css           Global CSS and design tokens
types/ov-server/         Supplemental typed server-result subsets

Keep route-specific implementation colocated under the corresponding route directory. Cross-route consumers must import an explicit public feature entry point instead of reaching into a -* module. Follow the Web Studio internationalization contribution guide whenever a feature adds or changes user-visible text.

Deployment

Web Studio deploys as static files from dist/. OpenViking Server remains a separate runtime dependency.

1. Start the Required Server

Production-like example:

openviking-server --host 0.0.0.0 --port 1933 --with-bot

Production deployments should configure server.root_api_key in ov.conf. If Web Studio and OpenViking Server are served from different origins, include the Web Studio origin in server.cors_origins.

Minimum health checks:

curl https://ov-api.example.com/health
curl https://ov-api.example.com/ready
curl https://ov-api.example.com/bot/v1/health

/bot/v1/health is part of the Web Studio deployment contract. A healthy core server without a healthy bot proxy is not enough for the sessions UI.

2. Build Static Files

For a separate frontend host:

cd web-studio
npm ci
VITE_OV_BASE_URL=https://ov-api.example.com npm run build

VITE_OV_BASE_URL is the initial OpenViking API origin used in the browser. Users can still change it in the connection dialog.

3. Serve from a Dedicated Host

Example URL:

https://web-studio.example.com/

Minimal nginx example:

server {
    listen 80;
    server_name web-studio.example.com;

    root /srv/web-studio/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

4. Serve from the Same Host Root

Example URL:

https://ov.example.com/

Proxy OpenViking API paths to the server and serve Web Studio at /:

server {
    listen 80;
    server_name ov.example.com;

    root /srv/web-studio/dist;
    index index.html;

    location /api/ {
        proxy_pass http://127.0.0.1:1933;
    }

    location /bot/ {
        proxy_pass http://127.0.0.1:1933;
    }

    location /health {
        proxy_pass http://127.0.0.1:1933;
    }

    location /ready {
        proxy_pass http://127.0.0.1:1933;
    }

    location / {
        try_files $uri $uri/ /index.html;
    }
}

Build with:

VITE_OV_BASE_URL=https://ov.example.com npm run build

5. Serve from a Same-Host Subpath

Example URL:

https://ov.example.com/web-studio/

In this layout, Web Studio is mounted under /web-studio/, while OpenViking API paths stay at the host root:

https://ov.example.com/api/*
https://ov.example.com/bot/*
https://ov.example.com/health
https://ov.example.com/ready

Build with both values:

cd web-studio
npm ci
VITE_OV_BASE_URL=https://ov.example.com npm run build -- --base=/web-studio/

Meaning:

  • VITE_OV_BASE_URL=https://ov.example.com: API origin used by browser requests.
  • --base=/web-studio/: Vite public asset base and TanStack Router mount path.

Publish dist/ to:

/srv/web-studio

nginx example:

server {
    listen 80;
    server_name ov.example.com;

    root /srv;

    location = /web-studio {
        return 301 /web-studio/;
    }

    location /web-studio/ {
        try_files $uri $uri/ /web-studio/index.html;
    }

    location /api/ {
        proxy_pass http://127.0.0.1:1933;
    }

    location /bot/ {
        proxy_pass http://127.0.0.1:1933;
    }

    location /health {
        proxy_pass http://127.0.0.1:1933;
    }

    location /ready {
        proxy_pass http://127.0.0.1:1933;
    }
}

Do not set VITE_OV_BASE_URL to https://ov.example.com/web-studio. /web-studio/ is only the frontend mount path; OpenViking API requests should still go to https://ov.example.com/api/* and https://ov.example.com/bot/*.

6. Docker Server Dependency

The official OpenViking image can be used as the API server dependency:

# Prefer ghcr.io. If it is hard to reach, use openviking-cn-beijing.cr.volces.com/volcengine/openviking:latest
docker run -d \
  --name openviking \
  -p 1933:1933 \
  -p 8020:8020 \
  -v ~/.openviking:/app/.openviking \
  --restart unless-stopped \
  ghcr.io/volcengine/openviking:latest

The image starts VikingBot by default. Do not pass --without-bot and do not set OPENVIKING_WITH_BOT=0 for a Web Studio deployment that needs sessions/chat.

Web Studio static files are still built and hosted separately unless your deployment image or platform explicitly bundles web-studio/dist.

Troubleshooting

/bot/v1/* Returns 503

The server was not started with --with-bot, or the VikingBot gateway failed to start. Install bot dependencies and restart:

uv pip install -e ".[bot,dev]"
openviking-server --with-bot

Check server logs for Bot API proxy enabled.

Client Generation Cannot Fetch OpenAPI

npm run gen-server-client reads http://127.0.0.1:1933/openapi.json. Start a local server first and use the same server version you plan to target at runtime.

Browser Shows CORS Errors

If Web Studio and OpenViking Server use different origins, add the Web Studio origin to server.cors_origins in ov.conf and restart the server. For same-origin deployment, proxy /api/, /bot/, /health, and /ready to OpenViking Server.

Connection Dialog Keeps Reopening

The API key is missing or invalid, the key belongs to a different server, or the selected account/user does not match the key scope. Verify the same server URL and key with a direct API request, then update the Web Studio connection settings.

Related Docs