GoRaven: a self-hosted agent runtime where the workspace is the product

The problem GoRaven picks, and the ones it deliberately drops

Most agent frameworks answer the question of how a model decides what to do next. GoRaven answers a different one: what does the agent run inside. The README states the design position directly under a heading called OS First. Models have knowledge and reasoning, but no eyes and no hands, so an agent that is supposed to get work done has to use operating system capabilities. The project's own framing is that a good agent is at its core an agent OS, except you cannot actually build an operating system from scratch. That sentence explains the Docker image more than any feature list does. The image bundles Go, Node.js, Python and Git, which is why the README says building from source is only recommended when you need to modify the code, and that non-development needs should use the image instead.

The audience follows from that. This is for teams that want agents reading and writing files, running shell commands, and calling internal APIs and private services, and who are not willing to send that traffic to a third-party host. The README's team-first claim is about isolation: each person gets an independent workspace, while projects and skill libraries are shared, and admins control model quotas, tool permissions and data access. Whether that admin surface is as complete as the sentence implies is something the README does not show.

The second design principle is the one worth arguing with. GoRaven states plainly that it does not do memory and evolution, on the grounds that anything which cannot be distilled into generalizable rules or handled by real-time retrieval augmentation is noise, and that the model's evolution is the model's own business. This is a real position, not marketing hedging. It means you should not expect the agent to accumulate user-specific preferences across sessions. What you get instead is retrieval: policies, docs and business materials go into RAG, and the agent retrieves context during execution. If your use case depends on an agent that learns your team over months, this project has told you up front that it is not that.

What actually runs: workspaces, RAG, skills and the hook layer

The architecture in the README is a diagram rather than a text description, so the mechanism has to be assembled from the feature claims. Four moving parts are named.

Workspaces are per-user and isolated, with shared projects and skill libraries layered on top. The README describes the result as a workstation rather than a chat window, and lists the operations an agent performs: reading files, writing code, running commands, calling APIs, searching the knowledge base, analyzing data, writing reports, building charts. It also claims the agent breaks a task down and works in parallel. No detail is given on how parallel branches are scheduled, how they are merged, or what happens when two branches write the same file. That is a gap, not a feature.

RAG is described as retrieval during execution rather than a separate question-answering step. The README's phrasing is that agents retrieve context in real time during execution, and that answers have sources. The ingestion side (chunking, embedding model, index storage) is not described in the README at all.

Skills are the packaging unit: prompts, scripts and workflows bundled together, installed with one click and maintained centrally. The README's pitch is that one person hitting a wall means the whole team skips it next time. That is a distribution mechanism, and it implies a skill format and a registry, neither of which the README specifies.

Plugin hooks are the most concrete extension point named. The README lists before and after conversations, tool calls, and SSE event streams as lifecycle points where custom logic can be injected, with the stated goal of deep customization without forking the core. If you are evaluating GoRaven seriously, this is the surface to inspect first, because it determines how much of your own policy you can enforce without maintaining a fork. The README gives the categories but not the function signatures, the registration call, or whether a hook can veto a tool call rather than only observe it.

Deployment is one container, and that is the whole install story

The quick start is two commands. Pull the image, then run it mapping port 8000:

docker pull 8treenet/goraven:latest

docker run -d --restart=always --name goraven-agent -p 8000:8000 8treenet/goraven:latest

For persistence, the README adds a volume mount at /goraven/data:

docker run -d --restart=always --name goraven-agent -p 8000:8000 -v /opt/goraven:/goraven/data 8treenet/goraven:latest

After startup you visit http://localhost:8000 and complete a setup wizard that creates the admin account. The container runs in UTC by default; the README shows -e TZ=America/New_York as the override and links to the tz database list for other values. There is also a RepoCloud one-click deploy button.

Building from source is documented as two steps: pnpm build inside frontend, then go run main.go from the repository root. The README is explicit that this path requires you to set up Go, Node.js, Python and Git yourself, which is the same list the Docker image bundles. The Go badge in the README specifies Go 1.25 or later, and the frontend stack is React 18 with TypeScript and Tailwind CSS 4.

What the README does not cover: TLS termination, running behind a reverse proxy, backup and restore of the /goraven/data volume, or how the container should be upgraded between releases. Given that three releases landed in the nine days before this snapshot (v0.5.1 on 2026-09-01, v0.5.3 on 2026-09-05, v0.5.4 on 2026-09-09), upgrade procedure is not a hypothetical concern. The volume mount is the only persistence mechanism named, so treating /opt/goraven as the unit of backup is the reasonable reading, but the project does not say so.

Where GoRaven is the wrong tool

The self-hosted position is the product, so it is also the constraint. If your team does not want to run a container, patch it, and own the data volume, GoRaven has no hosted offering in the material provided. The preview site at preview.goraven.dev is described as a live preview, not a managed service.

The refusal to build memory is a second boundary. An agent that cannot accumulate state across sessions will re-derive context every time, and the project's answer is retrieval instead. If your workflow depends on the agent remembering that a particular customer prefers a particular format, RAG is a weaker substitute, and the README says the project made that trade on purpose.

Third, and this is the one to take seriously before pointing the thing at anything valuable: the README claims admins control tool permissions and data access, but it does not describe the permission model. There is no mention of how shell execution is sandboxed, what the container's capabilities are, whether the agent runs as a non-root user, or how a tool call is authorized against a policy. The Docker image bundles Git, Python and Node.js, which is exactly what you want for capability and exactly what you do not want if the agent can be induced to run arbitrary commands. An agent with file write and shell access plus an LLM in the loop is a prompt-injection target, and the README does not address that class of problem. Treat the absence as an open question to resolve from the source, not as a solved problem.

Fourth, the design principle that agents have only three duties (deterministic workflows, precise tool invocation, robust execution) is a narrowing. If you want an agent that improvises novel multi-step strategies, GoRaven's stated philosophy is to make the instrument precise rather than clever, and the model's own capability is expected to carry the rest.

How it differs from LangChain-style libraries

GoRaven's topics list includes langchain, which makes the comparison fair to draw. LangChain is a library: you import it into a Python or JavaScript application you already own, you compose chains and agents in your own process, and you are responsible for the execution environment, the deployment topology and the user-facing surface. GoRaven is the opposite shape. It is a running service with a web UI, a database behind a mounted volume, a per-user workspace model, and a bundled runtime. You do not compose it into your application; you deploy it next to your application and let it call your APIs through MCP tool chains.

That difference decides most adoption questions. With LangChain you get fine-grained control over every step and no operational surface beyond your own app, but you also build the workspace isolation, the skill distribution, the admin quota layer and the UI yourself. With GoRaven you get those things preassembled and you give up the ability to change the execution model without forking or using the plugin hooks. The README's engineering-first principle is a direct statement of which side of that trade the project chose: it argues that agent tool combinations explode fast and that a small change to a pruning rule can send an execution flow off track, so the engineering investment is about the project still being worth working on next year.

A second axis is language. GoRaven's core is Go, which shapes deployment (a single static binary plus a bundled runtime) and the plugin story. LangChain's ecosystem is Python-first. If your team's tooling and internal APIs are Go, the hook layer is likely easier to work with than a Python library you would embed in a service you also have to operate.

Licence and the maintenance cost you are signing up for

GoRaven is Apache-2.0, which permits commercial use, modification and redistribution, and includes an explicit patent grant. It also requires that you preserve copyright and licence notices and state significant changes. That is the standard reading of the licence text; it is not legal advice, and if you plan to redistribute a modified GoRaven inside a product, have counsel read the NOTICE and modification clauses rather than relying on a summary.

The practical maintenance cost is the release cadence. Three releases in nine days is a project moving quickly, and the README's own engineering-first paragraph reads as an acknowledgement that agent codebases are easy to destabilize. For a self-hosted deployment that means you own the upgrade path. The README documents the Docker run command but not a migration procedure, so the questions to answer before you commit are whether /goraven/data survives a version bump and whether the schema inside it changes between minor releases. Nothing in the supplied material answers that.

There is also the runtime-image dependency. Because the image bundles Go, Node.js, Python and Git, you are tracking not only GoRaven's releases but the base image's contents, and any CVE in those bundled toolchains lands in your deployment. The upside is the same fact seen from the other side: you do not have to maintain those runtimes yourself, which is precisely the OS-first argument the README makes.

Who should run this, and what to check before you do

GoRaven fits teams that already run their own infrastructure, have internal APIs and private services they want an agent to call, and want per-person workspaces with a shared skill library rather than one shared chat account. The Docker deployment is genuinely short, and the decision to bundle the runtime is the reason it can be.

It does not fit teams that want a managed service, teams whose workflows depend on an agent accumulating memory across sessions, or teams that need a documented permission and sandboxing model before they will let an agent write files and run shell commands. The README states that admins control tool permissions and data access, but it does not show the mechanism, and that is the single largest gap in the material.

Concretely, before deploying against anything that matters, check three things in the v0.5.4 tree. First, the plugin hook registration path: confirm which of the named lifecycle points (before and after conversations, tool calls, SSE event streams) can block an action rather than only observe it. Second, the RAG ingestion configuration: the README does not name supported document formats, a chunking strategy, or an embedding model, so confirm your document types are accepted before you plan around retrieval. Third, whether the container runs its agent process as a non-root user and what the default tool permission set is on first boot, since the setup wizard creates an admin account and the README does not describe what that account can then authorize an agent to do.

Editorial conclusion

Adopt GoRaven if you need agents that touch files, shell and internal APIs, and you are willing to run the container yourself and read the plugin hook surface directly in the source. Do not adopt it if you want a hosted service or if you need the project to prove its own tool-permission model to you before you point it at production data. Verify first: which lifecycle hook points actually exist in the v0.5.4 tree, and whether the RAG ingestion path accepts your document formats.

Official sources

1. 8treenet/goraven on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases