Sandbox

The sandbox runs the whole of navin-manager on one workstation, without root and without Docker: a private PostgreSQL for the manager database, the server on 127.0.0.1:8460 (console and API) and 127.0.0.1:8461 (agent API and mirror), a sandbox cluster and a registered agent in rootless mode. It is meant for quick tests and demonstrations; production uses the packages and the external PostgreSQL of the bank.

Start

navin-manager/packaging/sandbox/sandbox.sh up

The script:

1. reuses the server environment navin-manager/server/.venv when it exists, else creates one in the state directory;
2. starts a private PostgreSQL 16 (pgserver) in the state directory;
3. creates the master key, applies the migrations and creates the administrator (password from NM_SANDBOX_ADMIN_PASSWORD, else generated and printed once);
4. starts the server in sandbox mode without TLS;
5. signs in through the API, creates the cluster sandbox and a bootstrap token;
6. registers the agent of navin-manager/agent with a file system prefix inside the state directory and the process driver, then starts it. With NM_SANDBOX_AGENT=go it builds and uses the static Go agent of navin-manager/agent-go instead (Go from NM_GO or PATH, or a binary given in NM_SANDBOX_AGENT_BIN).

The state directory is /tmp/navin-manager-sandbox (variable NM_SANDBOX_DIR). Ports 8460 and 8461 must be free: the script stops with a clear message otherwise.

Use

Command	Effect
sandbox.sh status	State of PostgreSQL, the server and the agent, and of the ports.
sandbox.sh logs server 200	Last lines of the server log (agent and postgresql also work).
sandbox.sh bundle opa,openfga	Fills the local mirror with the artifacts of these services (build-bundle.py) and reloads it in the server.
sandbox.sh down	Stops the agent, the components it runs, the server and PostgreSQL; the next up starts the components again. --purge also deletes the state directory.

Open http://127.0.0.1:8460, sign in as navin / navin (the console asks for your own password at the first sign in) and install a service in the sandbox cluster: for example OPA (method binary, mode standalone) or OpenFGA (method binary, mode memory, no database needed). The agent runs the components as supervised processes below its prefix, so nothing is written in /etc or /opt of the workstation.

What the sandbox allows

• A cluster in sandbox mode accepts the services reserved for tests, such as a local PostgreSQL (method python, with pgserver, or podman), so that a dependency can be satisfied without the bank cluster.
• The rootless agent ignores owners and groups, uses the process driver, and refuses the tasks that need root (system packages, kernel parameters, process limits, firewall, systemd units). The planner never sends them to it.
• Prerequisites that matter only in production (clock synchronization, systemd, SELinux) are reported as warnings.

Variables

Variable	Default	Effect
NM_SANDBOX_DIR	/tmp/navin-manager-sandbox	state directory (PostgreSQL, server, agent, mirror, logs)
NM_SANDBOX_CONSOLE_USER	navin	console account created by the server at its first start
NM_SANDBOX_ADMIN_PASSWORD	navin	initial password of that account, to change at the first sign in
NM_SANDBOX_ADMIN	admin	account the script uses for the API (password in <state>/admin.password)
NM_SANDBOX_BUNDLE_METHODS	binary	methods of sandbox.sh bundle
NM_SANDBOX_PYTHON	Python of navin-manager/server/.venv	Python of the server environment
NM_SANDBOX_AGENT	python	python or go (static Go agent of navin-manager/agent-go)
NM_SANDBOX_AGENT_BIN	none	built Go agent to use instead of a build (packaging/dist/agent-go)
NM_GO	go of PATH	Go toolchain that builds the Go agent

Troubleshooting

Symptom	Cause	Fix
up stops with a message about port 8460 or 8461	another program uses the port	stop it, or stop a previous sandbox with sandbox.sh down
NM_SANDBOX_AGENT=go needs the Go toolchain	no Go and no NM_SANDBOX_AGENT_BIN	set NM_GO, or give a built binary in NM_SANDBOX_AGENT_BIN
An installation stops with artifact_missing	the local mirror is empty	sandbox.sh bundle <services>
A task that needs root fails	the rootless agent refuses system packages, kernel parameters, limits, firewall and units	install with the binary or python method in the sandbox cluster
A clean start is needed	old state	sandbox.sh down --purge, then sandbox.sh up