Install and Prepare

Install the Base Packages

Download the Desktop App

If you want to use the One Works desktop app directly instead of assembling server + client in a project:

• Download the artifact for the pkg/oneworks-desktop/v* tag from GitHub Releases.
• macOS provides .dmg and .zip artifacts for Intel (x64) and Apple Silicon (arm64).
• Windows installers are not published yet. Follow #161.
• Linux provides .AppImage, .deb, and .tar.gz.

Current desktop artifacts are unsigned by default. macOS may show a security prompt on first launch and require manual confirmation.

Minimal Entry Points

For a quick start, use bootstrap:

npx oneworks "summarize the repo"
npx oneworks web
npx oneworks server
npx oneworks app
npx oneworks app cache
npx oneworks app --no-cache

oneworks lazily installs and forwards to the required runtime:

• web: forwards to @oneworks/web
• server: forwards to @oneworks/server
• app: remembers the last desktop install mode; if none exists, it asks whether to install into the user directory or bootstrap cache, then starts the desktop app with the current directory as the workspace
• app cache: explicitly uses the bootstrap cache and starts from it when the release is already cached
• app --no-cache: explicitly returns to user-directory install mode
• other commands: forwarded to @oneworks/cli

bootstrap app depends on a published desktop release for the current platform. macOS and Linux are available; Windows depends on published installer artifacts.

When opened through oneworks web, @oneworks/web, or a desktop workspace, the Web UI includes a module management page from the lower-left menu. It can inspect and update Core, Adapters, and Plugins. The default update channel is saved to the current workspace .oo.config.json as desktop.updateChannel; per-module overrides are saved as desktop.moduleUpdateChannels.

Project behavior of bootstrap app:

• The current shell directory is passed to the desktop app as the workspace.
• If the desktop app is already running for the same directory, the existing project window is focused.
• If the app is already running for another project, the same desktop process starts an independent service for the new directory and opens a new project window.

If you start the desktop app directly from an installer, it asks you to select a recent project or open a directory first.

To skip bootstrap, use concrete entry points:

npx oneworks web
npx oneworks server

• @oneworks/web: starts the built-in Web UI and server in one process. Default URL: http://127.0.0.1:8787/ui/.
• @oneworks/server: starts only the control-plane service for standalone PWA, static Web UI, or another app. Example: npx oneworks server --host 0.0.0.0 --port 8787 --allow-cors.

Package Manager Installers

Homebrew and Scoop metadata live in dedicated repositories and are generated after public One Works package builds are available.

• Homebrew tap: oneworks-ai/homebrew-tap
• Scoop bucket: oneworks-ai/scoop-bucket
• Supported commands: oneworks, ow, owo

Install the CLI on Windows

PowerShell one-line install:

irm https://raw.githubusercontent.com/oneworks-ai/app/main/scripts/install-windows.ps1 | iex

If your execution policy is strict:

iwr https://raw.githubusercontent.com/oneworks-ai/app/main/scripts/install-windows.ps1 -OutFile install-oneworks.ps1
powershell -ExecutionPolicy Bypass -File .\install-oneworks.ps1

Verify:

oneworks --version
oneworks --help

Scoop bucket manifests are generated by release automation after public package builds are available.

The public winget command becomes available after the manifest is accepted by microsoft/winget-pkgs:

winget install --id OneWorks.OneWorks -e

Until then, Windows users should use the npm entry point.

Install npm Packages in a Project

Integrated Web UI:

pnpm add -D @oneworks/web

Headless server:

pnpm add -D @oneworks/server

Advanced split deployments can install individual packages:

pnpm add -D @oneworks/server @oneworks/client @oneworks/cli @oneworks/adapter-claude-code

For ordinary project integration, prefer @oneworks/web. @oneworks/client is mainly for advanced split deployment or source development.

Third-party plugins must also be installed into the current workspace:

pnpm add -D @acme/oneworks-plugin-docs

Built-in One Works plugins use the runtime-declared version from the global package cache and do not need to be written into project dependencies.

Standalone binaries:

pnpm add -D @oneworks/mcp
pnpm add -D @oneworks/hooks

Or use npx without writing dependencies:

npx oneworks web --help
npx oneworks --help
npx oneworks web --help
npx oneworks server --help

Configuration and Data Directories

By default, One Works uses the resolved workspace root as the project configuration root and reads .oo.config.* / .oo.dev.config.* from there. CLI, Server, and Web entry points also read global defaults from ~/.oneworks/.oo.config.json.

Merge order:

1. global configuration as personal defaults
2. workspace .oo.config.* as project configuration
3. workspace or main-worktree .oo.dev.config.* as local overrides

Set disableGlobalConfig: true to skip the global layer for the current resolution. The flag is still merged by the normal global, project, and local priority rules.

The online configuration page can edit global, project, and local sources separately. CLI equivalents:

• oneworks config set --source global
• oneworks config set --source project
• oneworks config set --source user

Electron-only preferences such as launcher shortcuts, system app icon sync, icon theme, and background style are stored in the global config desktop section. The recent project list is desktop runtime state stored in Electron userData, not in the config system.

For data asset directory overrides such as __ONEWORKS_PROJECT_BASE_DIR__ and __ONEWORKS_PROJECT_ENTITIES_DIR__, see Data Asset Directories.