dash

An always-on assistant in front of hermes-agent.

The browser follows a reply through GET /api/jobs/<id>/events (SSE). The worker writes each reply to its own Redis stream, so a page reload replays the reply from the start.

The compose stack runs everything, Nango included. Nango needs NANGO_ENCRYPTION_KEY in .env. Make it with openssl rand -base64 32.

cp .env.example .env   # then set NANGO_ENCRYPTION_KEY
just docker up         # also: just docker down, nuke, logs [service], ps

Then open http://localhost:8000 (dash) and http://localhost:3003 (Nango, user admin). See compose.yaml for the other ports.

To run dash outside Docker:

docker run -d --name pg -p 5432:5432 -e POSTGRES_PASSWORD=dash pgvector/pgvector:pg16
docker run -d --name redis -p 6379:6379 redis:8-alpine
export DATABASE_URL=postgresql://postgres:dash@localhost:5432/postgres
export HERMES_BASE_URL=http://localhost:8642/v1 HERMES_API_KEY=...
uv run dash migrate
uv run dash worker &
uv run dash serve

To run the Helm chart (charts/dash) on Rancher Desktop (dockerd runtime, Traefik on):

just up                # builds dash:local, writes .local/secrets.json from .env, installs the chart
just ps                # also: just logs [-f] <deployment>, just scrape, just down, just nuke

Then open http://dash.localhost. values-local.yaml swaps RDS for an in-cluster pgvector and the ExternalSecrets for plain Secrets. The dash-bedrock Secret needs AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in .env. With no values, helm template renders the prod objects from geometry.dev/apps/dash.

The worker needs AWS credentials for Bedrock in the standard env chain. Outside Docker, Nango is optional. To use it, set NANGO_URL and NANGO_SECRET_KEY.

In the Apps tab, click Create GitHub App. Type an organization, or leave it empty for your personal account.

1. dash sends a manifest to GitHub. The manifest has the name, permissions, and redirect URLs.
2. On GitHub, you confirm the app. GitHub sends you back to /github/callback with a code.
3. dash exchanges the code for the app ID, private key, client secret, and webhook secret. Then it stores them.
4. GitHub opens the install page. After you install, /github/setup copies the installations from GitHub.

dash stores the private key and secrets as plain JSONB. Protect the database.

ArgoCD deploys dash from the Kustomize manifests in whatever/geometry.dev/apps/dash. They run the API, the worker, Redis (AOF), Nango, ExternalSecrets, and the Traefik ingress. compose.yaml is the reference for these parts.

On each push to main, CI does these steps:

1. It publishes the image ghcr.io/whatever/dash:sha-<short>.
2. It sends an image-published dispatch to geometry.dev.
3. geometry.dev opens a PR that bumps the image tag in apps/dash.
4. When that PR merges, ArgoCD syncs the new image.

CI needs the GEOMETRY_BUMP_CLIENT_ID variable and the GEOMETRY_BUMP_APP_KEY secret. The GitHub App must be installed on geometry.dev with contents write access.

Before the first sync, do these steps:

1. On RDS, as the master user, create the dash and nango databases. Then run CREATE EXTENSION vector in dash.
2. Add DASH_DATABASE_URL and NANGO_DATABASE_URL to geometry/config.
3. Create geometry/dash with NANGO_ENCRYPTION_KEY and NANGO_DASHBOARD_PASSWORD. Make the key with openssl rand -base64 32. Do not rotate it.
4. After Nango starts for the first time, copy NANGO_SECRET_KEY from its dashboard into geometry/dash and geometry/hermes.

hermes/skills/nango/SKILL.md is the hermes skill for connected apps. To use it, copy it into your hermes skills.

uv run ruff check && uv run ruff format --check && uv run pyright && uv run pytest