Workspace Is All Agents Need

English | 简体中文

Preview Notice

Zleap-Agent is still a preview release. Due to time constraints, this version focuses on demonstrating the core ideas of Agent Harness, Workspace isolation, memory partitioning, and WebUI/CLI collaboration. Many details will keep changing and improving in upcoming releases. Thanks for your patience, and feedback is welcome.

What Is Zleap-Agent?

zleap-agent-workspace-en-embed.mp4

Zleap-Agent is an Agent Harness developed specifically for local small-parameter models.

It focuses on the Agent Harness layer: if an agent sees every tool, every memory, every rule, and every past message on every step, a longer context window still wastes attention. This is especially painful for local smaller models and enterprise deployments where latency, cost, and data boundaries matter.

The Workspace idea is inspired by operating systems. When you open a computer, you first land on the desktop. The desktop gives you an entry point, organizes files, and launches applications, but real work still happens inside the right app: a document editor, terminal, browser, or design tool. Main Workspace plays the same role in Zleap-Agent: it talks to the user, understands the goal, and decides where to go next, while concrete execution happens inside Cli, Web Search, or another specialized Workspace.

The core idea is:

An agent should not see all context all the time. It should first know which Workspace it is in, then only see the tools, memories, prompts, and history needed by that Workspace.

This is similar to sparse attention at the system layer. Model architectures use sparse attention to avoid looking at every token; Zleap-Agent uses Workspace isolation to avoid showing the agent every piece of context.

Core Concepts

Workspace

Workspace is the most important concept in Zleap-Agent.

It is not a sub-agent and not just a tool group. A Workspace is an isolation layer for context, tools, memory, and models.

You can think of it as a workbench:

• Main: talks to the user, understands intent, and plans the work.
• Cli: has File and Command tools enabled by default, useful for local development and terminal work.
• Web Search: searches public web pages and reads selected URLs.
• Custom Workspaces: you can create spaces for engineering, sales, operations, finance, research, and more.

The same agent sees different prompts, tools, memories, skills, and models in different Workspaces. Main should not own every detail. It routes the task, while the actual execution happens in the right Workspace.

Context Is Not One Big Prompt

Zleap-Agent treats context as memory layout rather than raw prompt concatenation:

Context = System Prompt + Workspace Prompt + Tools + Memory + History

• System Prompt: global behavior and communication rules.
• Workspace Prompt: the current workbench, boundaries, and operating style.
• Tools: only the tools enabled for the current Workspace.
• Memory: relevant memory for the current task, not the full archive.
• History: recent conversation and essential execution trace, not the whole transcript.

Memory and history can be prefetched by the runtime or retrieved by the agent on demand. This keeps the model focused on what matters now.

Memory

Zleap-Agent does not use a single generic "long-term memory" bucket. Memory is partitioned:

• Person memory: user preferences, communication style, and long-term requirements. Users are isolated, and memories about the user are separated from memories about the agent itself.
• Event memory: facts, events, project state, and context for a specific user inside a specific Workspace.
• Experience memory: reusable methods extracted from completed work. Experiences belong to a Workspace and can be reused after sensitive details are removed.

Memory is database-backed because it participates in every agent loop. A database gives us isolation, retrieval, auditability, rollback, and a path toward multi-user deployment.

Skill

Skill is a reusable capability package. Zleap-Agent is designed to work with SKILL.md-based packages: the main file explains when and how the skill should be used, and the agent can read additional files or run bundled scripts when needed.

Tools are closer to APIs. Skills are closer to reusable workflows, instructions, and supporting resources.

Current Capabilities

• WebUI for chat, workspaces, assistants, models, tools, MCP servers, skills, memory, and artifacts.
• CLI powered by the same agent engine.
• Workspace-level tools, prompts, skills, memories, and model selection.
• Memory for person, event, and experience records.
• Built-in File, Command, and System tools, plus MCP Server support.
• Artifact display for generated Markdown, HTML, and other outputs.
• Two permission modes: full access and approval-required.
• Early Plan and Goal modes.

Quick Start

Requirements

• Node.js 20+
• pnpm 9.x
• Docker Desktop recommended, or a local PostgreSQL + pgvector installation

Install

git clone https://github.com/Zleap-AI/Zleap-Agent.git
cd Zleap-Agent

corepack enable
corepack prepare pnpm@9.15.0 --activate
pnpm install

Start WebUI

pnpm dev:web

This command will:

1. Start local PostgreSQL + pgvector.
2. Build required workspace packages.
3. Run database migrations.
4. Start the Next.js WebUI.

Open:

http://localhost:3000

If you already have a database:

ZLEAP_DATABASE_URL=postgres://user:password@127.0.0.1:5432/zleap pnpm dev:web

WebUI Usage

1. Open the WebUI and configure a model in Settings.
2. If you use an OpenAI-compatible gateway, you can fill the API key once in General Config and let Zleap-Agent create default LLM, embedding, and web-search settings.
3. Choose the permission mode: Full Access or Approval Required.
4. Choose a project folder if the task should modify that project directly. Without a project, outputs go to the default conversation workspace.
5. Choose a Workspace such as Main, Cli, Web Search, or a custom space.
6. Send a task. The agent will execute with the tools, memory, model, and skills configured for that Workspace.

CLI Usage

Build first:

pnpm build

One-shot run:

ZLEAP_MODEL_BASE_URL=https://api.example.com/v1 \
ZLEAP_MODEL_API_KEY=sk-... \
ZLEAP_MODEL_NAME=qwen3.6-flash \
ZLEAP_DATABASE_URL=postgres://zleap:zleap@127.0.0.1:5433/zleap \
pnpm --filter @zleap/cli start -- "Summarize this repository"

Allow high-risk tools in one-shot mode:

pnpm --filter @zleap/cli start -- --yes "Create a README draft in the current directory"

Interactive mode:

ZLEAP_MODEL_BASE_URL=https://api.example.com/v1 \
ZLEAP_MODEL_API_KEY=sk-... \
ZLEAP_MODEL_NAME=qwen3.6-flash \
ZLEAP_DATABASE_URL=postgres://zleap:zleap@127.0.0.1:5433/zleap \
pnpm --filter @zleap/cli start

Or link the CLI globally:

pnpm link:cli
zleap "Analyze the current project"

Common Configuration

Variable	Description
ZLEAP_DATABASE_URL	PostgreSQL connection string for workspaces, memory, skills, and persistence.
ZLEAP_MODEL_BASE_URL	OpenAI-compatible LLM base URL.
ZLEAP_MODEL_API_KEY	LLM API key.
ZLEAP_MODEL_NAME	Default LLM model name.
ZLEAP_EMBED_MODEL	Embedding model name.
ZLEAP_EMBED_BASE_URL	Embedding base URL.
ZLEAP_EMBED_API_KEY	Embedding API key.
ZLEAP_EMBED_DIM	Embedding vector dimension.
ZLEAP_FILE_WORKSPACE_ROOT	Default file root used when no project is selected.
ZLEAP_WEB_SKILLS_ROOT	Local skill directory scanned by the WebUI.
ZLEAP_SKILL_READ_TOKEN_BUDGET	Default token budget when reading skill content.
ZLEAP_SKILL_READ_MAX_TOKENS	Maximum token budget for skill reading.
ZLEAP_SKILL_RUN_TIMEOUT_MS	Timeout for running skill scripts.

Scheduled Task Worker

The Task module uses PostgreSQL + pg-boss. The WebUI creates, updates, lists, and enqueues tasks; cron firing and agent execution run in a separate worker process.

pnpm dev:web
pnpm tasks:worker

In production, run at least one zleap-task-worker process with the same ZLEAP_DATABASE_URL as the WebUI. Multiple workers may run at the same time; Postgres owns the queue locks.

Repository Layout

packages/
  ai/       model providers and model-call abstraction
  agent/    core agent types, Workspace, Skill, Tool, and Memory logic
  cli/      CLI entrypoint and runtime
  store/    PostgreSQL storage and migrations
  tasks/    scheduled-task service, pg-boss queue, and worker
  web/      Next.js WebUI
scripts/
  dev-web.mjs
docker-compose.yml

Common Commands

pnpm dev:web    # start database, migrations, and WebUI
pnpm tasks:worker # start the scheduled-task worker
pnpm build      # build all packages
pnpm test       # run tests
pnpm check      # build and type-check
pnpm cli        # start CLI

Project Status

Zleap-Agent is under active development. Near-term work includes:

• Better Workspace routing and model routing.
• Stronger memory extraction, retrieval, isolation, and rollback.
• More complete Skill compatibility, scanning, file reading, and script execution.
• Better WebUI for permissions, planning, goals, artifacts, and tool management.
• More end-to-end tests and benchmark harness coverage.

If you are interested in Workspace-first Agent Harness design, enterprise-local agents, memory partitioning, or small-model agent systems, feedback and contributions are welcome.