The Problem

Open Session addresses the pain of self-hosting agent infrastructure for coding sessions. Teams needing to coordinate coding work across multiple model APIs (Codex, Claude) and integrations (Slack, Linear, GitHub, Git worktrees) face a choice between expensive SaaS platforms or building custom infrastructure from scratch. This project provides the server, UI, and agent framework to run it all on your own hardware.

What This Does

Open Session is a self-hosted agent-infrastructure server (2683 files total) providing a web UI plus agents for Slack, Linear, Plain, and GitHub. The codebase centers on packages/core/opensession-server/ (the server) and packages/clients/ (desktop and web frontends). The website client runs on Next.js (packages/clients/website/), while the Mac client is a Electron/Tauri-like desktop app (packages/clients/mac/src/main.js). Agent logic lives under packages/core/opensession-server/src/agents/ — with dedicated handlers for GitHub, Grafana, Linear, and Plain. The "Pi engine" drives coding sessions through git worktrees, and the system can operate either on a local machine or in isolated sandboxes (Dockerfiles under deploy/sandbox/ and deploy/sandbox/lambda-microvm/). Configuration is written under a per-user config path; the install script writes a default config and sets up a user service (LaunchAgent on macOS, systemd --user on Linux).

Entry points: packages/clients/mac/src/main.js, packages/core/opensession-server/src/agents/github/index.ts, packages/core/opensession-server/src/agents/grafana-poller/index.ts, packages/core/opensession-server/src/agents/linear/index.ts, packages/core/opensession-server/src/agents/plain/index.ts

What the code touches: The server package handles agent intake, workspace management, and session orchestration. The website client (packages/clients/website/next.config.ts, package.json) provides the React UI. The Mac client (packages/clients/mac/src/main.js) is the desktop entry point. Agent handlers each parse incoming events from their respective platforms and translate them into session actions via the Pi engine. Sandbox deployment uses Docker (amd64/arm64) or Firecracker microVMs.

How It Is Wired

Internal call graph: Execution starts at the CLI (bun run setup or opensession command), which reads .opensession config and launches the server. The server (packages/core/opensession-server/) exposes an Express-based API that agents connect to. Each agent module (github/index.ts, linear/index.ts, plain/index.ts, grafana-poller/index.ts) receives webhook events, validates them, and dispatches to the Pi engine which manages git worktrees and session state. The website client contacts the server API to create sessions, view status, and manage integrations. The Mac client (packages/clients/mac/src/main.js) does the same via a native bridge. The packages/core/opensession-server/src/server/workspace-secrets.ts file contains secret-shaped path handling that was flagged in a code-health audit.

File-by-file responsibility map:

  • packages/core/opensession-server/package.json — server deps, start script
  • packages/core/opensession-server/src/agents/github/index.ts — GitHub webhook → session action
  • packages/core/opensession-server/src/agents/linear/index.ts — Linear webhook → session action
  • packages/core/opensession-server/src/agents/plain/index.ts — Plain webhook → session action
  • packages/core/opensession-server/src/agents/grafana-poller/index.ts — Grafana metric polling → session trigger
  • packages/clients/website/next.config.ts — Next.js config, routes
  • packages/clients/website/package.json — website deps, build
  • packages/clients/mac/src/main.js — Mac client entry, native bridge
  • deploy/sandbox/Dockerfile — sandbox container build
  • deploy/sandbox/lambda-microvm/Dockerfile — microVM sandbox build

The server is the hub: agents route through it, the UI routes through it, and the Pi engine runs inside it. A change to an agent handler typically requires a server restart; the website and Mac clients are relatively decoupled (they only need the API surface).

How To Use It

Setup:

git clone https://github.com/tellahq/opensession.git
cd opensession && bun install
bun run setup                             # interactive onboarding
# or unattended:
bun scripts/cli.ts onboard --defaults

Configuration: The install script writes a default config (.opensession/ under user home). Required env vars and keys are managed under Settings → Providers in the web UI (model API keys, GitHub token, Slack bot token, Linear API key). The config.example.json at root provides the schema. Tailscale, Caddy, or Cloudflare Tunnel can be installed for ingress.

Running it: After bun run setup, the service starts as a per-user unit. Verify with:

opensession status     # is the service up?
opensession doctor     # verify install and engine readiness

Real-World Use

A software engineering team wants to run coding sessions with Claude and Codex on their own infrastructure. They clone the repo, run bun install && bun run setup, add their model API keys in the Workspace → Providers panel, connect their GitHub account via Settings → Connections, and configure the GitHub agent intake under Settings → Integrations. A developer opens the UI, selects a repo, writes a prompt like "refactor the auth module to use passwordless login," and creates a session. The Pi engine checks out the repo into a git worktree, the Claude or Codex model acts on the code, and the session progresses with diffs, comments, and pull-request creation tracked through the UI. If the team needs isolation, they can deploy to the provided Docker or microVM sandbox templates instead of running bare metal.

Code Health & Issues

  • Low/Risk — Dependencies declared without a lockfile (package.json at root, packages/core/opensession-server/package.json, packages/clients/mac/package.json, packages/clients/website/package.json, packages/core/protocol/package.json): non-reproducible builds across environments.
  • Low/Security — Secret-shaped paths present: packages/core/opensession-server/src/server/workspace-secrets.test.ts, packages/core/opensession-server/src/server/workspace-secrets.ts. The code-health audit confirms these exist; verify they are handled correctly in production.

SDLC observations: 769 test files found (strong test coverage). 83 doc files found. CI/CD is GitHub Actions (workflows for bun dependency submission, CI, dependency audit, sandbox releases, secret scanning). No lockfile means bun lock or pnpm lock.yaml is absent; dependency resolution may drift.

The Bottom Line

Open Session is a functional, well-structured self-hosted agent platform that gives teams control over model APIs and integrations without SaaS lock-in. The code is TypeScript-heavy, heavily tested, and the sandbox/Docker deployment is explicit. The absence of a lockfile is the main reproducibility risk; teams running this in production should pin dependencies. It's best suited for teams that want to run coding sessions on their own infrastructure and are comfortable with the install/setup workflow.