peen

module
v0.3.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 11, 2026 License: MIT

README

peen

CI coverage version license Docker Pulls

Peen puts a coding agent in a real working directory and keeps the whole job alive after the first response. Connect a client over WebSocket, give it a task, and it can read code, edit files, run commands, use skills, launch child agents, and follow the rules sitting beside the project.

Every conversation, tool call, and agent event lands in SQLite. Reconnect with the same session ID after a restart and the history is still there. Open two clients on that session and both see the same live event stream.

Peen is the backend and harness. It does not ship a browser chat UI. Bring a browser client, terminal client, bot, or your own application.

Contents

Run it

Run Peen in Docker first. Pick a workspace you are happy to hand to an agent. Do not mount your whole home directory just because it is convenient.

You need Docker and a provider API key. Copy the example configuration:

cp .env.example .env

The example has AIGate and Z.ai entries. Keep the provider you use, set its model ID, and put its key in the named environment variable. For an OpenAI-compatible AIGate setup, the important lines look like this:

PEEN_UPSTREAMS=[{"name":"aigate","provider":"openai","baseUrl":"https://aigate.example/v1","apiKeyEnv":"AIGATE_TOKEN"}]
PEEN_DEFAULT_MODEL=aigate/your-model-id
PEEN_COMPACTION_MODEL=aigate/your-model-id
AIGATE_TOKEN=your-token-here
PEEN_API_TOKEN=

.env is a Docker --env-file, so leave the JSON unquoted. For a server outside your own machine, set PEEN_API_TOKEN to a real secret before starting it.

Build the image, create a private state directory, and mount the project the agent will work on:

make docker-build
mkdir -p ./data/peen ./workspace
sudo chown 10001:10001 ./data/peen ./workspace

docker run --rm \
  --env-file .env \
  -p 8080:8080 \
  -v "$(pwd)/data/peen:/data/peen" \
  -v "$(pwd)/workspace:/workspace" \
  peen run

./data/peen holds the database, logs, and harness configuration. ./workspace is the default directory the agent sees. Both survive a container restart.

Send it a task

With the default empty PEEN_API_TOKEN, open a browser console and paste this:

const sessionId = crypto.randomUUID();
const socket = new WebSocket(
  `ws://localhost:8080/v1/ws?sessionId=${sessionId}`,
);

socket.addEventListener("message", ({ data }) => console.log(JSON.parse(data)));
socket.addEventListener("open", () => {
  socket.send(JSON.stringify({
    type: "message.send",
    data: { message: "Read the project, then tell me what you would fix first." },
  }));
});

The generated sessionId is the conversation ID. Save it. Native agent events arrive while it works, then message.completed says that submission is done. The socket stays open for the next task.

Use the same session ID from several clients when you want them to see one conversation. Use a new UUID when you want a clean one. The full protocol, including browser authentication, failed turns, queued messages, and event fields, lives in the WebSocket API guide.

Provider configuration

Give every provider a short local name. Models are then addressed as provider/model, for example aigate/your-model-id or zai/glm-5.3. Peen asks each configured provider which models it actually offers at startup. A misspelled or unavailable model fails early instead of burning a turn.

It supports openai, anthropic, and zai-coding providers. zai-coding keeps Z.ai thinking state through tool rounds. A message.send can override the model for that one task. Peen never guesses task difficulty or silently switches models behind your back.

The full list of provider, context, tool, and event settings is in Configuration.

Make it understand your project

PEEN_CONFIG_DIR holds durable state and an optional base harness. The workspace adds project-specific instructions:

workspace/
  AGENTS.md
  .agents/
    skills/<skill-name>/SKILL.md
    agents/<agent-name>.md
    events/<event-type>.md
    hooks.yaml

Write ordinary project rules in AGENTS.md. Add a skill when the agent needs a named procedure. Add a named agent when it should delegate a bounded job. Use hooks when the harness itself must gate, annotate, or react to an action.

Peen resolves layers from the filesystem root down to the active workspace, so a repository can put broad rules at the top and narrow rules beside one component. The configuration directory can add a trusted base layer and holds the SQLite database, logs, and hook state.

Full layering, event, and hook details: Configuration and Hooks.

See what happened

The WebSocket is for live work. REST is for durable reads and control. It never starts a turn.

curl "http://localhost:8080/v1/messages?limit=50&order=asc" \
  -H "X-Session-ID: <session-id>"

curl -X POST "http://localhost:8080/v1/session/cancel" \
  -H "X-Session-ID: <session-id>"

REST also lists session state, pending events, process output, and child-agent runs. The API reference has every request and response.

Things worth knowing

Set PEEN_API_TOKEN and use wss:// outside local development. Browser WebSockets authenticate with subprotocols because browsers cannot attach an Authorization header. The API reference has the exact handshake.

Peen writes structured logs to stdout and keeps daily audit files under PEEN_CONFIG_DIR/logs by default. The active workspace is a default, not a containment boundary. An absolute tool path can still point outside it. Long conversations either drop old request context or replace it with a stored summary. Configuration covers all of this.

Security

Read this before you deploy Peen anywhere it can reach something you do not want touched.

Peen's host tools, run_command most of all, run with exactly the access of the operating-system user running the process. There is no sandbox, no path allowlist, no secret-file denylist, and no approval or permission step before a tool runs. A file tool can read, write, or remove any path that user can touch, including .git/, .env, and SSH keys. run_command executes an arbitrary shell command immediately. This is a deliberate design choice, not a gap: the product is a coding agent with real access, and Docker, the container user, and the mounts you choose are the isolation boundary, not anything inside Peen itself.

Tool calls and their results are recorded verbatim in the session transcript and sent live over the session's WebSocket connections, exactly like any other message. If the agent reads a file containing a secret, or a command prints one to stdout, that secret now exists in the SQLite transcript and in every client receiving the session event stream. Peen does not scan for or redact secret-shaped content in tool output. Treat the transcript and the event stream at the same sensitivity level as the files and commands the agent can reach.

remove_path has exactly one built-in restriction, and it is a guard against a catastrophic typo, not a permission system: it refuses to remove the filesystem root or the current message's workspace directory itself. Every other path, including everything named above, is removable.

Run Peen as a non-root user, in a container, with only the mounts, network access, and capabilities the deployment actually needs. The production image does exactly this by default; see below.

Docker deployment

The local Docker command above is the normal way to run Peen. The image has a real shell and the tools a coding agent uses. It runs as UID and GID 10001 under tini. For source builds, production mounts, networking, and container hardening, read Deployment.

Documentation

You want to Read
Start from zero Getting started
Configure providers, limits, logs, and harness layers Configuration
Build a WebSocket or REST client API reference
Add hard checks or model instructions around actions Hook configuration
Run it outside a local Docker command Deployment

What Peen is built with

Directories

Path Synopsis
cmd
repogen command
internal
app
pkg/agent
Package agent owns Peen's transport-independent agent runtime.
Package agent owns Peen's transport-independent agent runtime.
pkg/auditlog
Package auditlog adds a durable JSON sink beside the process logger.
Package auditlog adds a durable JSON sink beside the process logger.
pkg/config
Package config loads Peen's deployment configuration from PEEN_ variables.
Package config loads Peen's deployment configuration from PEEN_ variables.
pkg/db
Package db opens Peen's SQLite database, applies its embedded migrations, and wires the generated gorm/gen repositories.
Package db opens Peen's SQLite database, applies its embedded migrations, and wires the generated gorm/gen repositories.
pkg/events
Package events carries typed notices about things that happened which the agent did not directly ask about: a process job ended, a child agent finished, or something outside Peen reported a change.
Package events carries typed notices about things that happened which the agent did not directly ask about: a process job ended, a child agent finished, or something outside Peen reported a change.
pkg/hooks
Package hooks runs validated layered hook actions at agent lifecycle points.
Package hooks runs validated layered hook actions at agent lifecycle points.
pkg/http/api
Package api provides primitives to interact with the openapi HTTP API.
Package api provides primitives to interact with the openapi HTTP API.
pkg/http/server
Package server exposes Peen's client-facing Serbewr HTTP API.
Package server exposes Peen's client-facing Serbewr HTTP API.
pkg/metrics
Package metrics owns Peen's application Prometheus registry and its bounded runtime collectors.
Package metrics owns Peen's application Prometheus registry and its bounded runtime collectors.
pkg/session
Package session owns Peen's durable transport-neutral session transcript.
Package session owns Peen's durable transport-neutral session transcript.
pkg
http/api/client
Package client provides primitives to interact with the openapi HTTP API.
Package client provides primitives to interact with the openapi HTTP API.
peen
Package peen is Peen's stable, supported programmatic entry point.
Package peen is Peen's stable, supported programmatic entry point.
tests
testinfra
Package testinfra is the extendable integration-test harness for a servicepack app.
Package testinfra is the extendable integration-test harness for a servicepack app.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL