Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/agent0ai/space-agent/llms.txt

Use this file to discover all available pages before exploring further.

The user and group commands are out-of-process filesystem writers. They edit the logical L1 and L2 layers on disk through shared server libraries, but they do not notify a running server through IPC or the clustered worker mutation path. A live server observes these CLI changes through watchdog file watching and its periodic reconcile backstop — not through a direct channel.
Because user and group are out-of-process writers, changes land in the filesystem and propagate to a running server through file watching, not immediately. In SINGLE_USER_APP mode, user and group management commands have no effect on the implicit user principal.

​
user

node space user manages L2 user accounts. It supports two subcommands: create and password (alias passwd).

​
user create

Creates the full logical L2/<username>/ directory structure including user metadata, a backend-sealed password verifier, signed session storage, and a module folder. When CUSTOMWARE_PATH is configured, writes land under CUSTOMWARE_PATH/L2/<username>/.

​
Usage

# Minimal — username and password are both required
node space user create alice --password secret123

# Set a display name (defaults to username when omitted)
node space user create alice --password secret123 --full-name "Alice Example"

# Add the new user to one or more groups immediately
node space user create alice --password secret123 --groups _admin,team-red

# Replace an existing user directory
node space user create alice --password secret123 --force

​
Flags

​
--password
string
required
Password for the new user. Written as a backend-sealed verifier envelope to L2/<username>/meta/password.json. Required — create fails without it.
​
--full-name
string
Human-readable display name written to L2/<username>/user.yaml as full_name. Defaults to the username when omitted.
​
--groups
string
Comma-separated list of group IDs to add the new user to immediately after creation. Group IDs are normalized, de-duplicated, and sorted before membership writes. Any missing writable L1 groups are created automatically — including predefined runtime groups such as _admin.
​
--force
boolean
Replace the full L2/<username>/ directory if it already exists. Without this flag, create fails when the user directory is present.

​
Files created

PathContents
L2/<username>/user.yamlUser metadata including full_name
L2/<username>/meta/password.jsonBackend-sealed password verifier envelope
L2/<username>/meta/logins.jsonSigned session storage (initialized empty)
L2/<username>/mod/Per-user module folder

​
user password

Resets a user’s password and clears all active login sessions. The alias passwd is interchangeable with password.

​
Usage

node space user password alice --password newsecret456

# Alias form
node space user passwd alice --password newsecret456

​
Flags

​
--password
string
required
New password for the user. Rewrites meta/password.json and clears meta/logins.json to invalidate all existing sessions.

​
CUSTOMWARE_PATH effect

When CUSTOMWARE_PATH is set — either through node space set CUSTOMWARE_PATH=<path>, a launch override, or the process environment — all L2/... writes land under CUSTOMWARE_PATH/L2/... and any --groups writes land under CUSTOMWARE_PATH/L1/.... 
# Persist the path so both serve and CLI commands agree
node space set CUSTOMWARE_PATH=/srv/space/customware

# Now user create writes to /srv/space/customware/L2/alice/
node space user create alice --password secret123 --groups _admin

​
group

node space group creates and maintains writable L1 groups. It writes L1/<group-id>/group.yaml through shared server libraries and never touches L0 firmware groups, which are developer-maintained outside the CLI.

​
group create

Creates the logical L1/<group-id>/ root, initializes group.yaml with empty membership lists, and ensures a mod/ folder exists.

​
Usage

# Create a new group
node space group create team-red

# Replace an existing group directory
node space group create team-red --force

​
Flags

​
--force
boolean
Replace the full L1/<group-id>/ directory if it already exists. Without this flag, create fails when the group directory is present.

​
group add

Adds a user or group to the target group’s membership or manager list. Creates the target writable L1 group if it does not already exist — this allows predefined runtime groups like _admin to gain their first writable membership file without a separate group create.

​
Usage

# Add a user as a regular member
node space group add team-red user alice

# Add a user as a manager
node space group add team-red user alice --manager

# Add a nested group as a member
node space group add team-red group qa-team

# Add a nested group as a managing group
node space group add team-red group ops --manager

​
Flags

​
--manager
boolean
Switch the target list from included members to managing members. Without this flag, add writes to included_users or included_groups. With it, add writes to managing_users or managing_groups.

​
group remove

Removes a user or group from the target group’s membership or manager list.

​
Usage

# Remove a user from membership
node space group remove team-red user alice

# Remove a user from the manager list
node space group remove team-red user alice --manager

# Remove a nested group from membership
node space group remove team-red group qa-team

# Remove a nested group from the manager list
node space group remove team-red group ops --manager

​
Flags

​
--manager
boolean
Target the managing_users or managing_groups list instead of included_users or included_groups. Must match the flag used during add to remove from the correct list.

​
group.yaml structure

Each group’s L1/<group-id>/group.yaml file tracks four lists:
FieldModified by
included_usersgroup add <id> user <username>
included_groupsgroup add <id> group <other-id>
managing_usersgroup add <id> user <username> --manager
managing_groupsgroup add <id> group <other-id> --manager

​
CUSTOMWARE_PATH effect

When CUSTOMWARE_PATH is configured, L1/... writes land under CUSTOMWARE_PATH/L1/.... 
node space set CUSTOMWARE_PATH=/srv/space/customware

# Writes to /srv/space/customware/L1/team-red/group.yaml
node space group create team-red
node space group add team-red user alice

​
Combined workflow example

1

Configure the writable root

node space set CUSTOMWARE_PATH=/srv/space/customware
2

Create groups

node space group create team-red
node space group create team-blue
3

Create an admin user

node space user create admin --password "$(openssl rand -base64 24)" --groups _admin
4

Create a regular user and add to a team

node space user create alice --password secret123 --full-name "Alice Example" --groups team-red
5

Promote alice to a team manager

node space group add team-red user alice --manager
6

Start the server

node space serve

Build docs developers (and LLMs) love

Get started for freeTalk to us