Deployment and Compatibility

This page expands the manager overview into an operator-grade deployment and integration guide.

Deployment model

rauto-manager is designed as a self-hosted control plane for rauto agent fleets.

Typical production layout:

one central manager deployment
PostgreSQL as the persistent data store
one or more rauto agent instances in different network zones
operators accessing the manager through browser UI

Core runtime requirements

Required:

PostgreSQL database
DATABASE_URL
JWT_SECRET
AGENT_API_KEY

Optional but important in larger deployments:

NEXT_PUBLIC_AGENT_API_KEY
NEXT_PUBLIC_MANAGER_URL
NEXT_PUBLIC_MANAGER_GRPC_URL
AGENT_TIMEOUT
AGENT_HEARTBEAT_INTERVAL
MANAGER_GRPC_ENABLED
MANAGER_GRPC_HOST
MANAGER_GRPC_PORT
MANAGER_GRPC_MAX_MESSAGE_BYTES

First-run bootstrap

After startup, /login redirects to /setup on first boot so an administrator can create the initial account.

This means a production deployment should include:

database migration before first traffic
secure secret generation for JWT_SECRET
strong management of AGENT_API_KEY
controlled access to the initial bootstrap window

Standard self-hosted startup

npm install
cp .env.example .env
npx prisma migrate deploy
npm run dev

For schema iteration in development:

npx prisma migrate dev

Vercel deployment notes

The project supports Vercel deployment and includes vercel.json together with a build:vercel flow.

Important notes:

use a PostgreSQL database such as Neon
make sure DATABASE_URL points to the migrated database
set DIRECT_DATABASE_URL if Prisma migrations require a direct connection
commit migration files under prisma/migrations/
use separate databases or branches for production and preview
set JWT_SECRET and AGENT_API_KEY manually

Important limitation

The built-in manager gRPC server is not started on Vercel.

If you need gRPC-reporting agents, run the manager in a self-hosted Node environment and set:

MANAGER_GRPC_ENABLED=true

Agent connection modes

HTTP reporting mode

Use HTTP when the manager is reachable through its normal web address.

rauto agent \
  --bind 0.0.0.0 \
  --port 8123 \
  --manager-url http://<manager-host>:3000 \
  --report-mode http \
  --agent-name edge-sh-01 \
  --agent-token <same-agent-api-key>

gRPC reporting mode

Use gRPC when the manager exposes a gRPC listener in a self-hosted deployment.

rauto agent \
  --bind 0.0.0.0 \
  --port 8123 \
  --manager-url http://<manager-host>:50051 \
  --report-mode grpc \
  --agent-name edge-sh-01 \
  --agent-token <same-agent-api-key>

What the manager expects from agents

After registration, the manager expects an agent to support:

registration and heartbeat updates
offline notifications
full inventory sync
incremental reachability updates
live task execution events
task execution callbacks
async agent-side error reporting

HTTP compatibility contract

For full current UI behavior, an HTTP-reporting agent should expose at least:

GET /api/connections
PUT /api/connections/{name}
POST /api/connection/test
GET /api/templates
GET /api/device-profiles/all
GET /api/device-profiles/{name}/modes
POST /api/devices/probe

These endpoints support manager-side workflows such as:

connection inventory browsing
saved connection update and sync
connection testing
template discovery
profile lookup
device probe and sync

gRPC compatibility contract

For gRPC-reporting agents, the manager expects matching RPC behavior in the task and reporting services.

At minimum, that includes:

task dispatch
task event reporting
task callback reporting
connection list and save
connection test
template list
device profile list
profile mode lookup
device probing and sync

The manager automatically chooses HTTP or gRPC based on the saved agent report mode.

Dispatch types

The manager currently supports these task types:

Type	Description
`exec`	Send a single command through a saved connection
`template`	Execute a named template with variables
`tx_block`	Run a transaction-style command block
`tx_workflow`	Execute a workflow payload handled by the agent
`orchestrate`	Submit a multi-step orchestration plan

UI mapping:

simple dialog: exec, template, tx_block
visual designer: tx_workflow, orchestrate

Production design recommendations

Use manager when you need central control

Manager becomes worthwhile when you need:

multiple execution nodes
shared inventory
centralized task dispatch
live fleet-wide execution visibility
centralized history and notifications

Prefer saved connections on the agent side

Many advanced manager workflows assume the agent can expose or resolve saved connections cleanly.

Keep transport choice explicit

Use HTTP when:

deployment is simpler
only web-port exposure is practical
Vercel or edge-style hosting is involved

Use gRPC when:

you are self-hosting the manager
transport efficiency matters
you want manager-side control flows to remain entirely gRPC-based

Troubleshooting deployment issues

`The table public.Admin does not exist`

This usually means either:

prisma migrate deploy did not run successfully
the runtime is pointing to a different database or branch than the migrated one

Agent cannot register

Check:

AGENT_API_KEY on manager matches --agent-token
manager URL and port are correct
report mode matches the actual listener
firewall and network path allow traffic

gRPC agent cannot connect