Developer Environment Topologies

When building a Niksphere App, the Niksphere CLI, Niksphere Engine, and Niksphere VS Code Extension can be combined in several ways. The table below outlines the resulting topologies, where the Engine and its database run, how the editor is accessed, and what must be installed locally in each case.

Topology	Engine + DB	Editor	Local Requirements	Cloud Requirements
1. Local Native	Local Native	Local	Web Browser, Niksphere CLI, Niksphere Engine + DB, VS Code, Niksphere VS Code Extension	—
2. Local Container	Local Container	Local	Web Browser, Docker, VS Code	—
3. Cloud Container (Local Editor)	Cloud Container	Local	Web Browser, VS Code, GitHub Codespaces Extension	GitHub Codespace
4. Cloud Container (Browser Editor)	Cloud Container	Cloud	Web Browser	GitHub Codespace
5. Cloud	Cloud	Local	Web Browser, Niksphere CLI, VS Code, Niksphere VS Code Extension	Niksphere Cloud Environment

1. Local Native

The Niksphere CLI, Niksphere Engine, and Niksphere VS Code Extension are installed directly on the developer's machine, downloaded as native binaries and a .vsix package from the official Install page. Development happens in a local VS Code instance with the Extension installed.

This topology requires no container runtime and has no shared configuration across a team — each developer installs and updates the CLI, Engine, and Extension independently. It runs entirely on hardware the developer already owns and incurs no additional usage-based cost.

Related documentation:

• Engine Installation & Setup — Step-by-step guide to installing and running the Engine locally.
• CLI Installation & Setup — Step-by-step guide to installing the CLI locally.
• Engine Service Management — Running the Engine as a Windows Service or Linux systemd service.

2. Local Container

The CLI, Engine, and Extension run inside a Docker container defined by a devcontainer.json file checked into the App repository, together with a PostgreSQL database as a sibling container in the same Compose stack. A local VS Code instance attaches to this container via the Dev Containers extension.

Because the environment is defined in a versioned file rather than installed by hand, every developer on the team gets the same tool versions and the same database without following a manual setup guide. Like Local Native, it runs entirely on hardware the developer already owns and incurs no additional usage-based cost.

Related documentation:

• Dev Container Concept — Deep dive into the app/engine/db stack and the Niksphere Dev Container Features used to build it.
• Engine Deployment Concept — The Docker Container packaging used inside the devcontainer.json definition.
• Engine Database Concept — Background on the PostgreSQL database running as a sibling container.

3. Cloud Container (Local Editor)

The same devcontainer.json configuration used for the Local Container topology runs unchanged inside a GitHub Codespace instead of on the developer's own machine. Development still happens in a local VS Code instance, connected to the remote container through the GitHub Codespaces extension.

GitHub Codespaces is used here as the concrete example, but devcontainer.json is an open specification also supported by other cloud development environment providers, such as Ona (formerly Gitpod) — the same configuration is not locked to a single vendor.

Each developer's Codespace is a fully isolated container instance with its own Engine and database, so this topology requires no additional multi-tenant isolation on the Niksphere side. It runs on GitHub-operated infrastructure and is subject to GitHub's own usage-based Codespaces pricing, which may apply beyond a free allowance.

Related documentation:

• Dev Container Concept — Deep dive into the app/engine/db stack, and how it runs unchanged inside GitHub Codespaces.
• Engine Deployment Concept — The Docker Container packaging that also underlies this Codespace's devcontainer.json.

4. Cloud Container (Browser Editor)

Identical to the Cloud Container (Local Editor) topology, except the GitHub Codespace is accessed entirely through the Codespaces web client in a browser, with no local VS Code installation involved.

This is the only topology with no local footprint beyond a web browser, making it suitable for constrained devices or machines without administrative rights to install software. Cost is governed by the same GitHub Codespaces pricing as the Local Editor variant, since billing depends on the Codespace itself rather than on how it is accessed.

Related documentation:

• Dev Container Concept — Deep dive into the app/engine/db stack, and how it runs unchanged inside GitHub Codespaces.
• Engine Deployment Concept — The Docker Container packaging that also underlies this Codespace's devcontainer.json.

5. Cloud

The Niksphere CLI and VS Code Extension are installed locally as in the Local Native topology, but the Engine and its database are not run by the developer at all — they operate as a managed service in Niksphere Cloud. The CLI authenticates against this remote Environment instead of a locally running Engine.

This topology removes the need to operate an Engine and a PostgreSQL database altogether, at the cost of not having a private, per-developer instance the way the container-based topologies provide. It is subject to Niksphere's own usage-based pricing for the managed Engine and database service.

Related documentation:

• Engine Deployment Concept — Covers the Niksphere Cloud (Fully Managed) model this topology relies on.
• Managing Environments & Apps in VS Code — Connecting the Extension to a remote Environment.
• CLI Commands — Includes env auth login for authenticating against a remote Environment.