# kevinluosl/deepbot: a self-hosted AI agent for enterprise workflows

> DeepBot is an MIT-licensed Electron and TypeScript assistant that runs parallel agent sessions with a path whitelist and Feishu integration. The README is detailed about architecture and macOS builds, and silent about almost everything else.

**kevinluosl/deepbot** — DeepBot is a system-level AI assistant built for both personal productivity and enterprise workflows — one-click setup, seamless experience, and native Feishu integration.

- Repository: https://github.com/kevinluosl/deepbot
- Website: https://glint-mvt.com/deepbot/
- Stars: 2,199 · Forks: 166
- Language: TypeScript
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/kevinluosl-deepbot

## What DeepBot is trying to fix in enterprise AI use

Most AI assistants are a chat window with a text box. They answer questions. They do not open files, run commands, check a browser, or send a message into Feishu on your behalf. DeepBot is built for the second job. The README describes it as a system-level AI assistant focused on enterprise productivity, where "AI participates in day-to-day operations across departments through multi-Agent collaboration." The listed work is document processing, data analysis, system monitoring and cross-department coordination.

The intended user is not a solo developer looking for a coding copilot. It is someone inside a company who needs repeated operational work handled by an agent that can touch the local filesystem and external messaging, under a permission boundary. The README lists 20+ built-in tools covering file operations, command execution, browser control, image generation, image and video analysis, document analysis, cross-session messaging, web fetching, and Feishu, WeChat and WeCom messaging. That tool surface is the product. The chat interface is the delivery mechanism.

The Feishu integration is the clearest signal of the target audience. It is named as the external communication channel in the architecture diagram and appears again in the tool list. A team already running Feishu gets an agent that can be addressed from the tool they already use, rather than a new tab they have to remember.

## How the session, gateway and prompt layers fit together

The architecture diagram in the README shows a layered design. At the top is the Electron user interface, with Feishu as the external communication channel. Below it sits a Gateway that handles session management: one session per tab, a message queue and routing, connector management, and cross-tab message routing. Under the gateway, each session gets its own Agent Runtime instance.

The per-session isolation is the part worth understanding. Each runtime owns its own memory and context, and the diagram notes an auto-continue loop of up to 100 times and operation tracking capped at 3 retries. Those two numbers matter more than they look. An agent that keeps retrying a failing command is a liability, and the 3-retry cap is the documented answer to that. The 100-iteration auto-continue is generous; it suggests the authors expect long multi-step tasks rather than single-turn questions.

Below the runtime is a system prompt assembly layer. This is where the design gets interesting. The prompt is not one file. It is assembled at runtime from a base agent prompt (AGENT.md), tool instructions (TOOLS.md), custom tool instructions, global memory (MEMORY.md), per-tab memory (memory-<tab>.md) and skill instructions (SKILL.md). The README says this layer supports dynamic loading and live updates. Practically, that means you can edit a markdown file and change agent behaviour without rebuilding the app. It also means the effective prompt is a composition, and debugging a bad response requires knowing which file contributed the instruction.

At the bottom, the diagram places 14 tools behind a security check, with a path whitelist and workspace isolation. The feature list says 20+ tools; the diagram says 14. The README does not reconcile the two counts.

## Installing DeepBot from source and starting it

The README lists Python 3.11+ as a requirement, with Node.js 20.0.0+ and pnpm 10.23.0+ marked optional and described as needed for running JS scripts. The package.json declares Node 22 in the Docker build stage and pins pnpm 10.23.0 inside the Dockerfile, so the container path uses a newer Node than the README's stated minimum.

The source install is three commands. Clone the repository, install dependencies, start the dev server:

```bash
# Clone the repository
git clone https://github.com/kevinluosl/deepbot.git
cd deepbot

# Install dependencies
pnpm install

# Start in development mode
pnpm run dev
```

The dev script runs several processes concurrently: the Vite renderer, the TypeScript main process in watch mode, a template copy step, and then Electron once the dev server on port 5173 responds. Expect a terminal with interleaved output from all of them. The README does not describe what a successful first launch looks like beyond this.

For a packaged desktop build, the README gives `pnpm run dist` for all platforms, `pnpm run dist:win` for Windows, and two macOS variants. The difference between them is code signing. `dist:mac` uses an Apple Developer ID and notarization, passes Gatekeeper, and requires credentials in a `.env` file:

```bash
# Apple signing and notarization (macOS Electron builds only)
APPLE_ID=your-apple-id@example.com
APPLE_ID_PASSWORD=your-app-specific-password
APPLE_APP_SPECIFIC_PASSWORD=your-app-specific-password
APPLE_TEAM_ID=your-team-id
```

`dist:mac:local` skips signing and notarization entirely and needs no account. The README is explicit that these builds trigger macOS security warnings on first launch. If macOS reports the app is damaged, the documented fix is to clear the quarantine attribute:

```bash
sudo xattr -rd com.apple.quarantine /Applications/DeepBot.app
```

The alternative for the "cannot verify developer" warning is a right-click Open, or the Privacy & Security pane in System Settings. Both are described in the README.

Docker is the path most teams will want, and it is the least documented. The README states: "Docker deployment is available for Linux servers. If you need the Docker version, please contact the author." That sentence sits above a repository that contains a `Dockerfile` and a `docker-compose.yml`. The compose file exposes port 3008 by default, loads a `.env` file, and mounts seven host directories into `/data/*` paths for workspace, skills, memory, sessions, scripts, images and the SQLite database, plus a Playwright browser cache. The `.env.example` requires `AI_API_KEY`, `AI_BASE_URL` and `AI_MODEL_ID`, sets `AI_API_TYPE=openai-completions`, and warns that `JWT_SECRET` must be changed from its placeholder. The compose file's own comments warn that path variables must be absolute because `~` does not expand correctly in some environments.

## The path whitelist, the retry cap and other limits

The security model is a path whitelist plus workspace isolation. That is a reasonable boundary for an agent that reads and writes files, but it is a boundary you have to configure. The README does not explain how the whitelist is populated, whether it defaults to the workspace root, or what error an agent sees when it tries to write outside it. In Docker, the workspace is whatever `${WORKSPACE_DIR}` points at on the host, mounted to `/data/workspace`. The compose file's default is `~`, which its own comment says may not expand. If you deploy without setting that variable explicitly, you may be granting the agent more filesystem than you intended.

The retry and continuation behaviour is another place where the documentation stops short. The diagram gives a 3-retry cap on operations and up to 100 auto-continue iterations. It does not say what happens when the cap is reached, whether the session halts, reports an error, or silently moves on. For a tool that executes commands, that is the failure mode you most want documented.

There is also a gap between the marketing frame and the repository. The description calls the project "one-click setup" and "seamless." The README's own instructions are a git clone, a pnpm install, a dev server, and for macOS a signed build with four environment variables. That is not one click. The Docker route, which would be closest to one click, is the route the README tells you to ask the author about.

The tool counts do not agree either: 20+ in the feature list, 14 in the architecture diagram. One of the two is stale.

## DeepBot compared with a general agent framework

The closest comparison is a general-purpose agent framework such as OpenClaw, which appears in this repository's topic list alongside agentos, harness and harness-engineering. The difference is in what is packaged versus what you assemble.

A framework like OpenClaw gives you the agent loop, tool-calling primitives and a runtime you wire into your own application. You choose the UI, the persistence layer, the scheduling and the messaging integrations. DeepBot makes those choices for you: Electron for the interface, SQLite for storage, cron-style scheduling built in, Feishu as the external channel, and a prompt layer assembled from fixed markdown filenames. You get a working product faster and you inherit its opinions.

That trade runs in both directions. If your team uses Slack rather than Feishu, DeepBot's named external integration is the wrong one, and the README does not describe a plugin path for adding another. If you want the agent embedded inside an existing internal service, an Electron desktop app is the wrong shape, and the Docker mode exposes a web server on port 3008 rather than a documented API. The README does not describe an HTTP API for external callers, so treating DeepBot as a backend component is unverified ground.

Where DeepBot is genuinely differentiated is the prompt assembly layer. Loading base instructions, tool instructions, global memory, per-tab memory and skill instructions from separate files, with live updates, is a concrete design choice that a general framework leaves to you. Whether that is worth adopting the whole stack for depends on how much you value the built-in scheduling, memory and Feishu connector.

## Maintenance status, licence and upgrade cost

The repository is not archived, but the last push was on 2026-05-23. The most recent release in the repository is v0.7.2 from 2026-05-07, while package.json declares version 0.9.0. The version numbers in the release list and the manifest do not match, and the README does not explain the discrepancy. Treat the release notes as the authoritative changelog and check whether v0.9.0 was ever tagged.

The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive licence and it is the reason a company can build on this without a procurement conversation. It is not legal advice; if you redistribute a modified build, read the LICENSE file in the repository root rather than this summary.

Upgrade cost is where the design helps and hurts. Because the prompt layer reads markdown files at runtime, prompt changes do not require a rebuild. Code changes do. The build chain is TypeScript compiled through three separate tsconfig files (main, renderer, server), a Vite bundle, and electron-builder for packaging. There is a `type-check` script that runs the main and renderer configs, and a separate `type-check:server` for the server config. Running those before an upgrade is the cheapest way to find breakage. The Dockerfile also patches things at build time, deleting `@electron/rebuild` from devDependencies and stubbing the electron module with an empty Proxy, which means a Docker build can diverge from a desktop build in ways that are not obvious from the source.

## Conclusion

Adopt DeepBot if you want an agent runtime you can run yourself, with sessions isolated per tab, cron scheduling and a path whitelist you configure. Skip it if you need a documented API, published benchmarks or a project with an active maintainer, since the last push was on 2026-05-23. Before committing, verify the Docker path yourself: the README says to contact the author for the Docker version, while docker-compose.yml and Dockerfile sit in the repository.

## FAQ

### Is DeepBot down?

DeepBot is a self-hosted application, not a hosted service, so there is no central uptime to check. If your instance is unreachable, check the process on your own machine or server. In Docker mode the compose file defines a health check that requests /health on port 3008 and expects a 200 status code.

### What are the system requirements for DeepBot?

The README lists Python 3.11+, Node.js 20.0.0+ and pnpm 10.23.0+, with Node and pnpm marked optional and described as needed for running JS scripts. Supported operating systems are macOS, Windows desktop, and Linux or Docker.

### How do I install DeepBot with Docker?

The repository contains a Dockerfile and a docker-compose.yml that exposes port 3008 and loads configuration from a .env file, but the README states that Docker deployment is available for Linux servers and directs you to contact the author for the Docker version. Copy .env.example to .env and fill in AI_API_KEY, AI_BASE_URL and AI_MODEL_ID before starting the container.

### Which AI models does DeepBot support?

The feature list names Qwen, OpenAI and Claude among others. The .env.example gives AI_API_TYPE values of openai-completions, google-generative-ai and anthropic-messages, with example base URLs for OpenAI, Qwen, DeepSeek and Google Gemini.

## Sources

- [kevinluosl/deepbot on GitHub](https://github.com/kevinluosl/deepbot)
- [License: MIT](https://github.com/kevinluosl/deepbot/blob/main/LICENSE)
- [Project website](https://glint-mvt.com/deepbot/)
- [README](https://github.com/kevinluosl/deepbot/blob/main/README.md)
- [Releases](https://github.com/kevinluosl/deepbot/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kevinluosl-deepbot