!Nuphos — The Agent Workspace for your team.

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

• The session outlives your machine. A runtime can be local, a remote

• A session is a room with your teammates. Invite someone into a running

• Share and sync skills and tools across your team. Grant a skill or an

• Designed for professional users. The desktop puts a real GUI beside the

• A browser in the workspace. Open web pages in a desktop tab beside the

• Add the agent to Slack or Discord. One step drops the same agent into a

• Triggers. A schedule or a webhook starts a turn on its own — a cron, or

• Split the window. ⌘D splits side by side and ⌘⇧D splits top and bottom,

• Move the session between local, remote, and cloud. The conversation you

• Memory, with nothing to install. Memory across the team, across agents,

Apps

| Path | What it is | | -------------- | ----------------------------------------------------------------------- | | apps/backend | Bun/Hono API: accounts, teams, sessions, runtime registry, integrations | | apps/desktop | Electron/Vite/React client — the workspace itself | | apps/runtime | Claude Code / Codex container images, adapters and independent releases | | apps/ios | SwiftUI client: pick a session back up away from your desk | | apps/android | Jetpack Compose client for Nuphos Cloud |

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

The Zeabur button deploys the data stack. Then deploy the agent runtime in a separate project. 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.

For Zeabur, use deploy/zeabur/template.yaml; see the deployment inputs and setup guide. Railway project templates are also available.

What to know before you plan around it:

• One team per deployment. Teams are the scope for everything — sessions,

• The runtime signs in to Claude itself, once, from its own console. You

• Point the clients at your backend from the sign-in screen. Desktop and

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 ( local);
• the Desktop sign-in, ~/.config/nuphos/cli.dev..yaml;
• the logs, $TMPDIR/nuphos-dev-logs//.

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

• Titles follow Semantic Commit Messages, e.g.

• Develop and check backend-only changes from apps/backend and desktop-only

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(),

• Adding, removing or renaming a var updates apps/backend/.env.example in the

License

Apache-2.0.