SteamHarness guide

SteamHarness is a platform for building, running, and distributing Agent projects. It consists of the Core SDK, CLI, Studio, Server, and the Server Web console. Projects can be developed locally, uploaded to a Server, and published to Store.

Three project types

Type	Form	Best for	Entry point
Workflow	Typed TypeScript workflow	Automation, multi-step tasks, tool orchestration	Entry function + nodes / executor
Conversation	Conversational Agent project	Assistants, Agent conversations	Conversation executor
Kanban	Static HTML / CSS / JavaScript	Boards, visualizations, human-in-the-loop	index.html

Workflow

A Workflow describes a runnable task chain with nodes and executors: inputs, LLM calls, tools, branches, loops, and outputs are declared through the Runtime API. It is a good fit when a set of operations needs typed steps and reuse.

• Typical uses: data processing, content generation, tool calling, multi-step automation.
• Start with Workflow model and Core API.

Conversation

Conversation is an Agent project organized around conversation turns, tool calls, and session data. It uses the same Core Runtime, but its entry point is a message or conversation rather than a single task chain.

• Typical uses: assistants, support/operations assistants, Agents that need ongoing context.
• Start with KV and conversations and Core API.

Kanban

Kanban is a static project made of HTML, CSS, JavaScript, images, and fonts. It loads index.html, does not execute the Runtime API, and needs no executor. A restricted bridge lets the page read project KV and knowledge documents.

• Typical uses: boards, maps, dashboards, visual interfaces embedded in conversations or project details.
• Start with Kanban HTML projects.

Where projects run

SteamHarness separates execution from management:

Location	Executes project code	Purpose
Studio / local CLI	Yes	Run and debug locally, inspect traces
Server	No	Stores source, versions, members, KV, knowledge, and project files
Server Web console	No	Manage projects, members, and data in the browser
Store	No	Browse, download, and publish version archives

The Server does not install project dependencies, build, or load uploaded project code. A Kanban preview is a static iframe bound to a project, user, and version; it does not inherit account credentials and is not project execution on the Server.

Main features

Capability	What it does	Entry point
Studio	VS Code OSS-based workstation to open and run local projects, inspect traces, and manage versions and accounts	Using Studio
Local CLI	Check project structure, run projects, open the web workspace	Local CLI
Server and Server Web	Manage project source, versions, members, knowledge, KV, and accounts	Server Web console
Workspace CLI	Sign in to a Server, upload/download source, publish and switch versions	Workspace CLI
Store	Browse, download, and publish project versions	Store overview
System AI (Enhanced)	Shared models, personal defaults, provider preference, usage, and orders	System AI guide
Built-in projects	Developer Assistant, Codex, Conversation, OpenCode, Pi, and other ready-to-use projects	Release notes

Project data and configuration

The location of project data is declared in package.json under steamHarness.projectInfo.dataStorage; the runtime rejects access outside the declaration:

Mode	Allowed location	Notes
local	Local only	The CLI can run offline
server	Server only	Requires sign-in and the same project UUID binding
both	Local and server	Each access explicitly chooses a location

• KV / PersistentValue: accessed through context.storage.local or context.storage.server; the two sides are separate data sets.
• Knowledge and project files: stored by the Server and managed in the Server Web console.
• Project configuration: configuration.json declares fields (string, number, boolean, JSON, file); values are managed in Studio, CLI Web, or the Server Web panel. Mark sensitive fields with secret: true.
• Related projects: projectInfo.relatedProjects declares an alias, the target project UUID, and read/write grants; both sides must declare the relationship.

Changing dataStorage only changes future allowed locations; it does not migrate existing data. See Project data storage, Project configuration, KV and conversations, and File inputs.

Accounts, permissions, and collaboration

The Server uses accounts and fixed project roles:

Role	What it can do
guest	View the project, released versions, KV, knowledge, files, and previews; download released source and run locally
developer	Edit drafts, upload and publish versions, and modify server KV, knowledge, and project files
maintainer	Manage project information, public state, official configuration, guests, and developers
owner	Assign all roles, manage owners, delete the project, and transfer ownership

Projects can live in groups, and groups can have nested subgroups. The effective role is the highest of the direct project role and any inherited group role. Public projects grant guest access to every signed-in user; private projects can accept access requests through a released version's share link. See Project management.

AI capabilities

In open source, each project owns its model: declare an LLM provider and API key in the project, and nodes read the configuration at runtime. The Server does not store or proxy third-party model credentials. See LLM provider.

Enhanced adds System AI on top: the platform maintains the model catalogue, credentials, and billing; users choose a default model and provider preference, subscribe or use balance, and review usage and orders. The Studio assistant uses System AI directly after signing in to a project. See What Enhanced adds: System AI configuration.

Development workflow

1. Create a project: in Studio, choose New Project, then a Workflow, Conversation, or Kanban type and template; or create the directory manually.
2. Declare the project: add steamHarness.projectType (workflow, conversation, or kanban) to the root package.json, plus optional projectInfo (names, display platforms, data storage, related projects).
3. Write the entry point: Workflow / Conversation use the Core Runtime API for the entry and executor; Kanban starts from index.html and static assets.
4. Run locally: open the project in Studio and run it, or use steamharness structure ., steamharness run ., and steamharness web ..
5. Upload to a Server: use the Workspace CLI to sign in, package the source, and publish a version; manage the project, members, and data in the Server Web console.
6. Publish to Store (optional): create a Store entry from a version already on the Server, submit it for review, and list it.

Project structure

A minimal Workflow / Conversation project usually contains:

my-project/
├── package.json   # name, steamHarness.projectType, projectInfo, Core/CLI versions
├── index.ts       # entry point and executor
└── ...

A Kanban project only needs:

my-board/
├── package.json
└── index.html

package.json is the source of truth for project information. steamHarness.projectType selects the project type; steamHarness.projectInfo stores localized names, display platforms, data storage, and related projects. Workflow / Conversation must pin exact Core and CLI versions in devDependencies; Kanban only uses the Core version as static package metadata.

Built-in projects

Studio ships with projects you can open or create directly:

Project	Purpose
Developer Assistant	Helps understand projects, generate code, and carry out development tasks in Studio
Studio Control	Gives Agents controlled access to Studio operations
Studio Analysis	Summarizes local projects and run state
Codex / Conversation / OpenCode / Pi	Ready-to-use Agent / conversation projects

Built-in projects follow the same project types, versions, and permissions. See Release notes for version history.

Versions, testing, and deployment

• Versions: Core, CLI, Server, Server Web, and built-in projects release independently; projects pin exact Core and CLI versions in devDependencies. See Release notes and Version compatibility.
• Migration: see the Core 0.1 to 0.2 migration guide.
• Testing: steamharness structure . checks project structure; see Automated testing for project tests and repository gates.
• Deployment: see Deployment and publishing for Server, Server Web, and Store.

Choose your next step

• New to SteamHarness: start with Using Studio.
• Writing business logic: see Core API and Workflow model.
• Managing server projects: see Workspace CLI and Server Web console.
• Using System AI or publishing to Store: see Enhanced features.