User Guide Remote Mode

Remote Mode

Prev: Output and Report Formats | Up: User Guide | Next: Remote Protocol Reference

ReqPack has two automation-oriented serve modes:

1. rqp serve --stdin: read commands from stdin until EOF.
2. rqp serve --remote: start a TCP server and execute commands from remote clients.

This page covers remote TCP mode, remote.lua semantics, auth, supported protocols, and operational caveats.

Start a Remote Server

Examples:

rqp serve --remote --bind 127.0.0.1 --port 4545 --token secret
rqp serve --remote --json --readonly --max-connections 4

Important flags:

• --bind <addr>: default 127.0.0.1
• --port <n>: default 4545
• --token <value>: fallback token auth
• --username <name> and --password <value>: fallback basic auth
• --readonly: allow only read-only commands
• --max-connections <n>: concurrent client limit
• --json: force JSON Lines protocol for all clients
• --http and --https: reserved for future work, not implemented yet

Configure Remote Profiles

Client profiles and server-side user definitions live in remote.lua.

Path:

• $XDG_CONFIG_HOME/reqpack/remote.lua
• fallback: ~/.config/reqpack/remote.lua

Minimal example:

profiles = {
  dev = {
    host = "127.0.0.1",
    port = 4545,
    protocol = "auto", -- auto | text | json | http | https
    token = "secret",
  },
}

users = {
  admin = {
    token = "secret",
    isAdmin = true,
  },
}

Notes:

• a profile can use host or url
• host or url can include host, port, and optional scheme; explicit port field wins if both are present
• protocol can be auto, text, json, http, or https
• http and https profiles currently fail because those protocols are not implemented
• a server user can authenticate with token, or with username/password basic auth
• for basic auth, username defaults to the user ID if omitted
• if at least one valid users entry exists, server prefers that user registry instead of fallback --token or --username/--password
• in built-in rqp remote client, auto currently behaves like text mode; use explicit json if you want JSON client mode

Connect as a Client

Examples:

rqp remote dev list apt
rqp remote dev install apt curl

Behavior:

• if you pass a command, rqp sends it once and exits
• if you pass only the profile name, rqp starts an interactive text session
• interactive sessions therefore require text-mode behavior; do not use protocol = "json" if you want an interactive shell

Example interactive flow:

rqp remote dev
list apt
search npm react
exit

Supported Protocols

There are two related behaviors to understand:

• server behavior: when server runs without --json, it speaks text protocol and can also auto-detect raw JSON requests per connection
• built-in rqp remote client behavior: protocol = "json" uses JSON mode, while protocol = "text" and protocol = "auto" both use text client mode today

Use --json only when you want to force JSON Lines for every client.

Text mode

Text mode is the default and the most capable mode.

It supports:

• interactive sessions,
• token auth,
• basic auth,
• local file upload for install <system> <local-file>.

Token auth handshake:

auth token secret

Basic auth handshake:

auth basic admin hunter2

Server replies with a text frame shaped like:

OK <length>
<plain text output>

or

ERR <length>
<plain text output>

<length> is byte length of response body, so custom clients should read exact body size rather than waiting for a prompt.

JSON mode

JSON mode is for one-shot programmatic commands. It does not support interactive sessions.

Example request:

{"command":"list apt","token":"secret"}

Example success response:

{"ok":true,"output":"...plain text command output..."}

Example failure response:

{"ok":false,"error":"...plain text error output..."}

Important limitation:

• JSON mode does not support local file upload.
• if you need install <system> <local-file>, use text mode.

File Upload Behavior

rqp can upload a local file through the text protocol when you run a remote install command that targets one local file.

Examples that work in text mode:

rqp remote dev install rqp ./my-tool.rqp
rqp remote dev install dnf ./package.rpm

Restrictions:

• only regular files are supported
• only one local file per install command
• text protocol only

Admin Commands

If a remote user has isAdmin = true, the session can run these server commands:

• shutdown
• connections count
• connections list
• reload-config

These are not normal package-manager commands. They are server control commands handled directly by the remote runtime.

Read-only Mode

Read-only mode is useful for dashboards, observability, and safe remote queries.

Allowed actions in readonly mode:

• list
• search
• info
• outdated
• sbom
• audit

Blocked in readonly mode:

• install
• remove
• update
• ensure
• any command that writes an output file through outputPath

That means even sbom or audit are rejected in readonly mode if they try to write a file on the server.

Server-side Config Interaction

serve --remote reloads its baseline behavior from normal config.lua too.

Useful keys:

remote = {
  readonly = false,
  maxConnections = 16,
}

CLI flags win over config. For example, if you start with --readonly, the server stays readonly even if config.lua says otherwise.

Security Recommendations

• Bind to 127.0.0.1 unless you deliberately want remote access from outside the host.
• Prefer explicit users in remote.lua over a single fallback token.
• Use --readonly for query-only automation.
• Use JSON mode for simple machine-to-machine calls and text mode for human sessions or uploads.
• Do not document or depend on http/https yet; they are placeholders today.

Related Pages

• Configuration
• Remote Protocol Reference
• Architecture Overview
• Execution Flow

Prev: Output and Report Formats | Up: User Guide | Next: Remote Protocol Reference