A self-hosted, Slack-like workspace where people and coding agents build together.
Following the success of Happy,
Happy (2) is a ground-up next chapter built on the lessons learned from
bringing coding agents into real daily workflows. It brings conversations,
files, workspaces, and coding agents into one focused web and desktop app.
Built by the authors of
Happy and
Rig.
Quick start ·
Configuration ·
Why Happy (2)? ·
How it works ·
Project components ·
Server docs
Happy (2) is a self-hosted, Slack-like work and coding app that evolves by
adopting itself. It gives teams and coding agents a shared home instead of
scattering work across chat windows, terminals, file browsers, and one-off
dashboards.
The same React application runs in the browser and in Electron. A small Fastify
server provides authentication, durable collaboration state, files, realtime
updates, and agent execution. The complete server and web app are also bundled
as one `happy2` package.
## Quick start
Happy (2) requires Node.js 24 or later. Start the complete app with one command:
```sh
npx happy2
```
Open [http://127.0.0.1:3000](http://127.0.0.1:3000) in your browser. Happy (2)
stores its database, files, generated secrets, agent workspaces, and private Rig
runtime under `.happy2` in the directory where you start it.
Run it in the background without installing an operating-system service with:
```sh
npx happy2 daemon start
npx happy2 daemon stop
```
The daemon stores `happy2.pid`, the combined `happy2.log`, and the error-only
`server-error.log` under `./.happy2`. Stopping it terminates the daemon process
tree and removes the PID file.
Keep Happy (2) running across reboots with:
```sh
npx happy2 service start
npx happy2 service stop
```
On macOS this installs a per-user LaunchAgent without `sudo`; it starts when the
user logs in. On Linux it writes and prints `./happy2.service`, then shows the
exact `sudo` commands you can run to install and start it as a system-wide
systemd unit. `service stop` prints the corresponding systemd removal commands;
it never invokes `sudo` itself. The generated file remains in the current
directory so you can inspect or reinstall it. Add
`--config /absolute/or/relative/happy2.toml` to `service start` to preserve an
explicit configuration file; otherwise the service keeps the current directory
as its working directory and uses its `.happy2` state. When started through
`npx`, the generated service runs `npx --yes happy2` instead of depending on an
evictable `_npx` cache path.
## Configuration
Happy (2) uses the following configuration precedence:
1. `--config /path/to/happy2.toml`
2. `HAPPY2_CONFIG=/path/to/happy2.toml`
3. `./.happy2/happy2.toml`, when it exists
4. Built-in defaults
TOML configuration is partial. Happy (2) recursively merges the supplied fields
over the built-in defaults, so this is enough to expose the public listener:
```toml
[server]
host = "0.0.0.0"
```
The managed path is relative to the directory where Happy (2) starts. Relative
database, file, plugin, key, and agent paths are also resolved from that working
directory, not from the TOML file's directory. The standalone `happy2` and
`happy2 backend` commands use this configuration; `happy2 web` has its own CLI
options because it only serves the SPA and proxies `/v0`.
### Complete TOML reference
All supported keys are shown below. Uncomment optional keys only when needed.
The active values are equivalent to the built-in local defaults. For readability,
paths are shown relative to the working directory; generated defaults store those
same locations as absolute paths.
```toml
[server]
# all: authentication + product API; auth: authentication only; api: validation only
role = "all"
host = "127.0.0.1"
port = 3000
public_url = "http://127.0.0.1:3000"
# Number of trusted proxies outside Happy (2). Keep 0 for direct connections.
trusted_proxy_hops = 0
[database]
url = "file:.happy2/happy2.db"
# Name of the environment variable containing a remote libSQL auth token.
# auth_token_env = "HAPPY2_DATABASE_AUTH_TOKEN"
[agents]
enabled = true
# These default to the private Rig runtime under .happy2/rig.
# socket_path = ".happy2/rig/server.sock"
# token_path = ".happy2/rig/token"
# command = "/absolute/path/to/rig"
default_cwd = ".happy2/workspaces"
[files]
provider = "local"
directory = ".happy2/files"
signed_url_expiry_seconds = 300
max_upload_bytes = 536870912
resumable_chunk_bytes = 8388608
# Zero disables the corresponding quota.
per_user_quota_bytes = 0
server_quota_bytes = 0
incomplete_upload_expiry_seconds = 86400
quarantine_retention_seconds = 2592000
# malware_scanner_command = "/usr/local/bin/clamscan"
malware_scanner_arguments = []
malware_scan_timeout_seconds = 120
malware_scan_failure_mode = "deny" # deny or allow
[plugins]
directory = ".happy2/plugins"
# Capability-only API used by plugin containers. Firewall it from untrusted networks.
host_api_host = "0.0.0.0"
host_api_port = 3001
# Omit this table to disable public agent-port sharing. Configure wildcard DNS
# and TLS for *.preview.example.com to reach the same Happy web listener.
[port_sharing]
public_domain = "preview.example.com"
# Optional; defaults to https://preview.example.com.
# public_url = "http://preview.example.com:8080"
[security]
# Name of the environment variable containing the integration encryption secret.
integration_secret_env = "HAPPY2_INTEGRATION_SECRET"
[security.rate_limit]
enabled = true
reads_per_minute = 1200
writes_per_minute = 300
auth_per_minute = 30
[security.idempotency]
enabled = true
lease_seconds = 30
retention_seconds = 86400
[jwt]
issuer = "http://127.0.0.1:3000"
audience = "happy2-desktop"
key_id = "local-generated"
expiry_days = 30
# PEM files may replace environment or generated keys.
# private_key_path = "/run/secrets/happy2-jwt-private.pem"
# public_key_path = "/run/secrets/happy2-jwt-public.pem"
# Password is the default. Set it to false before enabling magic link, OIDC,
# or Cloudflare Access; exactly one authentication method may be enabled.
[auth.password]
enabled = true
[auth.dev_tokens]
# This augments the selected authentication method; it is not a separate method.
enabled = false
[auth.magic_link]
enabled = false
# from = "Happy (2)