Nuphos

The agent workspace for your team.

Coding agents are single-player by default: one agent, on one laptop, in one
terminal, for one person. Nuphos is where a team runs them instead — across
people, across machines, and without the session ending when someone closes
their lid.

Features

• Use your existing agent. Claude Code and Codex ship today, each behind an
  ACP adapter. You keep the coding-plan
  subscription you already pay for — the runtime signs in with that account,
  and there is no extra model charge on top.
• The session outlives your machine. A runtime can be local, a remote
  machine you own, or one Nuphos manages. Close the laptop and the turn keeps
  going; pick it up from your phone in the iOS app.
• A session is a room with your teammates. Invite someone into a running
  session the way you would a Notion page. Several people talk to the same
  agent, see the same tool calls, and steer together.
• Share and sync skills and tools across your team. Grant a skill or an
  integration once and every agent on the team has it, synced, rather than each
  person pasting a token into their own machine.
• Designed for professional users. The desktop puts a real GUI beside the
  conversation: a Kubernetes GUI for the cluster, a Grafana GUI for dashboards,
  alerts, logs and traces, plus GitHub and Linear for repositories, pull
  requests and issues. GitLab, AWS including ECS, GCP, Cloudflare, Linode, and
  your MongoDB and SQL connections sit alongside them.
• A browser in the workspace. Open web pages in a desktop tab beside the
  conversation — docs, a dashboard, the app you are working on — with its own
  history, instead of switching windows.
• Add the agent to Slack or Discord. One step drops the same agent into a
  channel the team already uses.
• Triggers. A schedule or a webhook starts a turn on its own — a cron, or
  an incoming event — without anyone sitting in the chat.
• Split the window. ⌘D splits side by side and ⌘⇧D splits top and bottom,
  so you can watch several agent sessions at once. Drag a chat from the sidebar
  onto a pane's edge to open it there, or drag a pane by its grip to move it.
• Move the session between local, remote, and cloud. The conversation you
  are in switches to this computer, another machine you own, or a cloud
  runtime, and keeps going.
• Memory, with nothing to install. Memory across the team, across agents,
  and across sessions is built in. There is no MCP server to add before one
  agent can recall what another learned.

Apps

See apps/android/README.md for Android build and test
instructions. The Android client currently uses Nuphos Cloud sign-in; custom
self-hosted endpoints are not yet supported.

The agent runtime lives in apps/runtime (Apache-2.0).
Its image executes a turn, and a self-hosted deployment registers its own.
See apps/runtime/README.md for building, running
and independently releasing the runtime.

Releases

Maintainers publish Desktop downloads and self-hosted Backend images through
component-specific release tags. See the release guide for
versioning, required approvals, and signing setup. Hosted-service deployment is
managed separately. Read it before planning or cutting any release; the runtime
has its own runtime-vX.Y.Z tags, covered in
apps/runtime/README.md. Automated releases may only
produce Patch or Minor versions — a Major needs an explicit manual X.0.0.

Self-hosting

Railway currently uses the CLI deployment guide rather than a published
one-click template.

deploy/compose brings up a complete, minimal Nuphos with one
docker compose up — MongoDB, S3-compatible storage, the backend, and one agent
runtime. Start at deploy/compose/README.md.

Railway project templates are also available.
For Kubernetes, install the Helm chart.

What to know before you plan around it:

• One team per deployment. Teams are the scope for everything — sessions,
  skills, memory, integrations — but the hosted product is where multiple teams
  in one instance live.
• The runtime signs in to Claude itself, once, from its own console. You
  supply your own account; there is no key to configure in Nuphos.
• Point the clients at your backend from the sign-in screen. Desktop and
  iOS both have a "Self-hosted? Set API endpoint" link there, and email
  sign-in works against any backend. Emailing codes needs a Resend key;
  without one, nuphos-admin in the backend image creates the first user and
  team and prints sign-in codes and server join tokens (see the
  Helm README). A launch-time NUPHOS_API_URL (as
  bun run dev sets) is Desktop's starting endpoint and can still be changed.
  Google sign-in goes through the nuphos.ai web page, so it only works
  against Nuphos Cloud.

Not available self-hosted: managed runtime provisioning, managed backups, and
the operational tooling that comes with running this as a service.

Connected accounts

The GUI panes are not screenshots — the agent operates the accounts behind
them. Cloud providers are the sharpest case: AWS access is a cross-account
assume-role and GCP is service-account impersonation, so your deployment's
identity has to be the trusted principal on the other side. A self-hosted
instance binds accounts to itself, not to nuphos.ai.

Contributing

See CONTRIBUTING.md. CI runs on every pull request:
typecheck, tests, lint, import-cycle and format checks across the apps your
change touches.

Prerequisites

• Bun for apps/backend.
• Node.js 22 and pnpm 10 for apps/desktop.
• Docker (Docker Desktop, or Docker Engine with Compose v2.24+) and openssl for the local stack bun run dev runs on.
• Google OAuth credentials and NUPHOS_JWT_SECRET for Nuphos auth flows.

Formatting and Linting

Prettier is configured once at the repo root (.prettierrc.json), with per-app
overrides so each app keeps the semicolon/quote style it already uses. ESLint is
per-app, because each app has a different package manager and framework preset.

bun install          # at the repo root — installs Prettier
bun run format       # rewrite
bun run format:check # report only (what CI runs)

cd apps/backend  && bun run lint   # type-aware: no-floating-promises, no-misused-promises
cd apps/desktop  && pnpm lint      # react-hooks / react-refresh

Optional pre-commit hook

A format-only hook lives in .githooks/. It is opt-in — enable it once per
clone:

git config core.hooksPath .githooks

It runs prettier --check on staged files only. It deliberately does not run
ESLint: the backend config is type-aware, so a lint pass builds a full
TypeScript program and is far too slow for a commit hook. Use
git commit --no-verify to bypass it.

Local Development

From the repository root:

bun run dev

It starts the local stack, backend, runtime and Electron Desktop with isolated
configuration. Do not start Desktop on its own or use the web-only Vite server
as the default dev loop.

Parallel instances

Every worktree or clone can run bun run dev at the same time. All of them
share one Mongo / RustFS / runtime stack, whose secrets live in
~/.config/nuphos/dev-stack.env. The first run copies the main checkout's
deploy/compose/.env, and takes the S3 keys from the running stack when there
is one. If that file and the running stack ever disagree, bun run dev stops
before recreating the stack under the other instances; copy the stack's keys
into the file, or wipe the stack with bun run dev:reset. Everything else derives from the instance
name, which is the checkout's directory name or NUPHOS_DEV_INSTANCE:

• the backend, Vite and DevTools (CDP) ports, each claimed free at start;
• the Desktop profile, Nuphos Dev (<name> local);
• the Desktop sign-in, ~/.config/nuphos/cli.dev.<name>.yaml;
• the logs, $TMPDIR/nuphos-dev-logs/<name>/.

Two checkouts with the same directory name, or two instances from one
checkout, need different NUPHOS_DEV_INSTANCE values. Sign-ins from the old
shared cli.dev.yaml are not carried over, so each instance signs in once; the
backend prints the email code in the dashboard.

bun run dev:instances           # name, state, ports, disk usage and worktree of each instance
bun run dev:instances rm <name> # stop it, then delete its profile, sign-in, logs and clean worktree

rm stops only that instance's own launcher and processes, and leaves the
shared stack and the main checkout alone. It does not remove a worktree that has
uncommitted changes. An e2e harness should attach to the CDP port that
dev:instances lists, never to a fixed port.

Working Guidelines

AGENTS.md and CLAUDE.md point coding agents here, so this section is the
single source of repository rules for people and agents alike.

Pull requests

• Open PRs ready for review. Use a draft only when the change is genuinely
  unfinished or a draft was asked for.
• Titles follow Semantic Commit Messages, e.g.
  fix(agent): improve agent chat traces, with no tool prefix such as
  [codex].
• Develop and check backend-only changes from apps/backend and desktop-only
  changes from apps/desktop. A contract change that affects both lands in one
  PR so the API and the desktop client stay compatible.

Backend environment variables

apps/backend/src/config.ts and the section files under
apps/backend/src/config/ are the only place backend env vars are read and
documented. src/config.env-sync.test.ts enforces the rules below in CI.

• Read env only through the helpers in src/config/env.ts (required(),
  optional(), bool(), …), in the section that owns the feature. No other
  file under src/ or scripts/ may touch process.env or Bun.env; tests
  and the test's BYPASS_ALLOWLIST are the exceptions.
• Adding, removing or renaming a var updates apps/backend/.env.example in the
  same PR, with a comment and a sensible placeholder. Platform-injected vars
  (HOSTNAME, GIT_SHA, …) go in the test's INFRA_ALLOWLIST instead.

License

Apache-2.0.