Configuration, files and ports
Where a node keeps its settings and state, how its settings are layered, and the network ports it uses.
A node keeps everything it needs in one state directory, reads an optional settings file an administrator provides, and needs no inbound port unless it is a team hub.
Settings
A node's settings come from two files. The second wins where both set the same key.
| Layer | File | Who writes it |
|---|---|---|
| Administrator | /etc/mojoup/node.json on Linux and macOS, %ProgramData%\MojoUp\node.json on Windows. --config or MOJOUP_NODE_CONFIG names another file. | An administrator or a machine image. The node only reads it. |
| The node's own | settings.json in the state directory | mojoup-node config set, the setup wizard, and a person with the right access over the Control API. |
Use the administrator's file to provision a fleet: the state directory, tags, and so on. Use config set for one machine:
mojoup-node config get node.name
mojoup-node config set node.tags tag:gpu,tag:linux
mojoup-node config set node.autoUpdate install
mojoup-node config set node.home /srv/work --createconfig get with no key lists every setting that is set and where its value comes from. A list setting takes a comma-separated list or a JSON array; null removes a setting.
Settings a node uses most
| Setting | Default | What it does |
|---|---|---|
node.name | the host name | The name the organisation lists the node under. |
node.tags | none | Tags the node asks for when it joins and runs, such as tag:gpu. The approver can change them; assignment happens in the console, never on the node. |
node.roles | teams | What the node offers to do: teams, inference, dlp, sandbox, computer. |
node.home | the user's home folder | Where the node clones repositories and runs agent tools from. It never holds the node's own state. |
node.stateDir | see below | Where the node keeps its state. Read only from the administrator's file. |
node.owner | org | Who the node is offered as belonging to: the organisation, the person who joins it (user) or one project. The approver decides. |
node.maxConcurrentAgents | 0 (no limit offered) | The most agents the node runs at once. The organisation's quota still applies. |
node.acceptsDispatchFrom | none | Narrows whom the node accepts work from (project:<id>, group:<name>, user:<id>, tenant). It can narrow, never widen, what the organisation assigns. |
node.approvalTimeoutSeconds | 300 | How long a tool permission request waits for someone to answer before the node denies it. |
node.approvalHoldSeconds | 1800 | How long a request is held once it has reached the organisation's inbox (the console and the phone app) before the node denies it. |
node.autoUpdate | notify | off, notify (record and log that an update is available) or install. |
node.consent.modelDownload | false | Whether the node may download the local model runner and a model when asked. Off declines. |
node.consent.organisationPolicy | replace | When the organisation publishes a policy for a repository that has its own, replace it (replace) or keep the repository's (keep). |
node.sandbox.engine | off | The container engine for agent sandboxes: off, docker or podman. See Sandboxed nodes. |
Every setting, with its full description, is on the Settings page; the node-only ones start node..
The state directory
The node picks its state directory in this order:
--state-dir(or--state) on the command line.- The
MOJOUP_NODE_STATE_DIRenvironment variable. node.stateDirin the administrator's settings file.~/.mojoup/node, or/var/lib/mojoup/nodewhen run as root on Linux or macOS.
What it holds:
| Path | What it is |
|---|---|
settings.json | The node's own settings layer. |
projects/ | The projects and repositories the node serves. |
state.json | The node's install id. |
platform.json | Which organisation the node joined. |
secrets.bin | Encrypted secrets and tokens. |
status.json | What the running node last reported; mojoup-node status prints it. |
schedules.json | Routines kept on this node. |
hosts/ | Per-repository working storage. |
mesh/ | The mesh agent's key and status. |
logs/node.log | The node's log. logs/service.log when it runs as a service or daemon, logs/update.log for updates. |
audit/ | The audit log of every change made through the node. |
team-hub/ | Everything a node that is the team's hub keeps. |
control.token, control.sock | The local control connection, present only while the node runs. |
Back up the state directory to keep a node's identity and settings. The install folder holds no state: removing it and installing again loses nothing.
The secrets key
The node encrypts its secrets with a key kept in the operating system's store where there is one: DPAPI on Windows, the Keychain on macOS, the Secret Service (secret-tool) or systemd credentials on Linux. Where none is available it falls back to a key file and warns about it in status. Run mojoup-node secrets status to see where the key is and mojoup-node secrets migrate to move a key file into the operating system's store.
The install folder
| Default | As root | |
|---|---|---|
| Linux and macOS | ~/.local/share/mojoup/node | /opt/mojoup/node |
| Windows | %LOCALAPPDATA%\MojoUp\Node |
Inside it: versions/ (the installed version and the one before it), current (a link to the version in use, which PATH and the service point at) and install.json (where the node was installed from and its channel).
Network and ports
| What | Direction | Port |
|---|---|---|
The organisation's platform, or Mojo Up AI Cloud at https://ai.mojoup.com.au | Outbound HTTPS | The platform's HTTPS port |
| Mesh control listener | Loopback only (127.0.0.1); the mesh agent exposes it on the node's mesh address at the same port | 7434 by default (platform.mesh.port) |
Team hub (mojoup-node hub) | Inbound HTTPS on the address it binds (the tailnet by default) | 7431 by default (--port) |
| Local control connection | A Unix socket (or a named pipe on Windows), owner-only | None |
A node that joins an organisation or Mojo Up AI Cloud needs no inbound port: it makes every connection outwards. On a self-hosted organisation that runs a mesh, the console and your other machines reach the node through the encrypted mesh, which also needs no inbound port. Only a node running as a team hub listens for other machines.
mojoup-node doctor checks that the platform is reachable and that the mesh control listener is open.
Behind a proxy
The mesh agent reaches your organisation through the system's proxy by default. platform.mesh.proxy sets it explicitly: direct for none, or a proxy URL.