Install and configure

Install, update and configure the library; API root, generated code and dedicated server keys.

#Install

#From s&box (recommended)

Install from sbox.game/sboxcool/network-storage, or in the editor:

1. Open Editor > Library Manager.
2. Search for Network Storage and pick the one published by sboxcool. Do not install copies from other authors.
3. Click Add to Project. The library appears in your project's Libraries/ folder.

#Manual (git)

cd "YourProject/Libraries"
git clone https://github.com/sbox-cool/sbox-network-storage "Network Storage by sboxcool"
# or, as a submodule from the project root:
git submodule add https://github.com/sbox-cool/sbox-network-storage "Libraries/Network Storage by sboxcool"

The editor does not pick up a library folder added while it is running: restart the editor (or reopen the project) after cloning. Checked on s&box 26.10.13.

#Updating

Use Library Manager; it replaces the library folder. For a manual install, git pull inside the folder, or delete the old Libraries/<library folder> completely and install again. Do not copy new files over an old install: files moved between versions (for example JsonHelpers.cs, NetLog.cs and NetworkStorageClient.cs now live under Code/Core/) would exist twice and the project fails to compile with duplicate-type errors (CS0121).

Library versions before 1.0.309133 do not start on s&box editor 26.10 or later (Constructor on type 'SyncToolWindow' not found). Update the library.

#Unreleased features (main)

main can contain merged fixes that are not yet published on sbox.game. The self-hosted owner dashboard lists them, with how long they have waited. To try them:

1. Close the editor.
2. Delete (or back up) the library folder in Libraries/.
3. Extract https://github.com/sbox-cool/sbox-network-storage/archive/refs/heads/main.zip into Libraries/ and rename sbox-network-storage-main to sboxcool.network-storage, or git clone the repository into that folder.
4. Start the editor.

To go back, delete that folder and install from sbox.game. Unreleased code has passed the GitHub Actions compat gate but not the native editor run a published release requires: do not ship games built on it. main can need a newer server than the published library.

#Configure

#1. Get a project and keys

Use a self-hosted server (sbox-ns quickstart "My Game" prints everything below) or create a project on sboxcool.com. You need:

• the Project ID;
• a public key (sbox_ns_...): used by the game at runtime, safe to ship;
• a secret key (sbox_sk_...): editor tooling and trusted dedicated servers only, never in a published game.

#2. Enter them in the editor

1. Open Editor > Network Storage > Setup.
2. Enter the Project ID, Public API Key and Secret Key. For a self-hosted server, set Base URL to its scheme and host (for example https://my-game.sboxns.com, no path or trailing slash). Leave CDN URL empty unless you run one.
3. Click Save Configuration, then Test Connection.

Credentials are saved to Editor/Network Storage/.env. The Editor/ folder is excluded from s&box publishing and .env is gitignored, so the secret key never ships or gets committed.

The Sync Tool window shows the active server (highlighted when it is not api.sboxcool.com) and the last request it sent.

#Or configure in code

NetworkStorage.Configure( projectId, publicKey );                       // api.sboxcool.com
NetworkStorage.Configure( projectId, publicKey, "https://your-server" ); // self-hosted

The full signature is Configure( projectId, apiKey, baseUrl, apiVersion, cdnUrl, publishTarget, securityKeyFingerprint ); see encrypted requests for the fingerprint.

#API root

New projects get apiVersion v3 (https://your-server/v3/...). The hosted backend at api.sboxcool.com does not serve the /api/{family} routes, so api works only on self-hosted servers 0.5.5 and later: set apiVersion to api in Editor/Network Storage/config/public/projectConfig.json, or pass "api" as the fourth argument of Configure. A config without an apiVersion key keeps v3. /api/storage uses uniform storage routes only for library 1.2.0 and later; older libraries keep their legacy meaning.

#Generated code

After a sync or pull the Sync Tool writes into your project:

• Code/Data/NetworkStorage/: Readme.txt and autoGenerated_Config.cs, _Collections.cs, _Endpoints.cs, _Workflows.cs. They are regenerated every time; do not edit them.
• Assets/network-storage.credentials.json: project ID, public key, base URL, API version and auth/encryption flags, never the secret key. It ships with the game, so point baseUrl at the server players should use before publishing.

#Dedicated servers

A dedicated server can supply the secret key at launch without putting it in the published bundle:

sbox-server.exe +game your.org.game your.map +hostname "My Server" +network_storage_secret_key sbox_sk_your_secret_key

+network_storage_secret_key is the primary name. On Application.IsDedicatedServer hosts the library also accepts +network-storage-secret-key, +sboxcool_secret_key, +networkStorageSecretKey, +sboxcoolSecretKey, +nsSecretKey and +ns_secret_key, and validates the key at startup. Generic names such as +secret-key, +secret_key and +secretKey are intentionally not supported.

With the dedicated key the library does not request or send s&box auth tokens. Endpoint requests carry the secret in the x-secret-key HTTPS header; storage document reads, writes and deletes send it as x-api-key, so secret keys with collections:execute can reach endpoint-only collections. Never put sbox_sk_ values in code, public credentials or client-callable URLs. Collection schema deletion stays in the dashboard.

#Security model

• Only the public key ships in a game. Anything it can do, any player can do, so keep game data behind endpoints.
• Anti-exploit checks run on the server: endpoints recompute each claim from game values and the server clock and reject impossible results. The checks bound what a client can claim; they cannot prove a hit landed.
• New collections start in accessMode: endpoint; direct document calls from game clients get 403 ENDPOINT_ONLY.
• The library runs in API only mode: runtime reads and editor sync use the API; there is no local JSON fallback.