Deployment

Deployment posture

Enrai is not designed like a public SaaS dashboard. It is a high-trust workspace that can edit files, run shell commands, and drive agent workflows in a real directory.

That means the first deployment decision is not “which cloud?” but “what trust boundary am I operating inside?”

Internal-first deployment model

Enrai is designed for:

• local development
• trusted internal environments
• hosts behind a firewall
• machines where file access and shell execution are intentional features

Recommended flow

Portable mode

Portable mode serves the editor frontend from the same Express process used by the backend:

npm run build:portable
npm run start:portable

URL:

http://localhost:3001/editor

Portable mode is usually the best default when:

• the same team owns frontend and backend changes
• the runtime sits on a trusted workstation, VM, or internal server
• you want the least operational drag for local and internal usage

Split frontend and backend

You can also serve the frontend and backend separately.

This is useful if you want:

• a managed frontend on Vercel or Amplify
• a separate VM/container for the Enrai backend
• different deploy cadences for UI and backend

In this model:

• frontend/ is deployed as a normal Next.js app
• backend/ is deployed separately on your own host
• the frontend points to that backend through NEXT_PUBLIC_EDITOR_BACKEND_URL

Example:

Frontend: https://editor.example.com
Backend:  https://enrai-api.example.com

Frontend environment variable:

NEXT_PUBLIC_EDITOR_BACKEND_URL=https://enrai-api.example.com

The editor will then call:

https://enrai-api.example.com/api/...
https://enrai-api.example.com/ws
https://enrai-api.example.com/api/enrai/tasks

If you use the Enrai task queue from external automation, you can also configure a completion callback URL so Enrai sends a POST when a task finishes as completed, failed, or interrupted.

Choose this model when:

• the UI belongs on Vercel, Amplify, or another frontend platform
• the backend must stay on a private host with WebSocket and filesystem access
• your release cadence for the UI differs from the runtime host

Vercel

For a Vercel frontend:

1. Import the repository in Vercel.
2. Set the root directory to frontend.
3. Add NEXT_PUBLIC_EDITOR_BACKEND_URL.
4. Deploy the backend separately on your own machine, VM, or container host.

AWS Amplify

For an Amplify frontend:

1. Create a new app from this repository.
2. Set the app root to frontend/.
3. Add NEXT_PUBLIC_EDITOR_BACKEND_URL in the environment settings.
4. Deploy the backend separately and expose it through your preferred proxy/domain.

Notes:

• The backend still needs WebSocket support.
• The backend should usually sit behind Nginx, Caddy, Apache, or another reverse proxy.
• If you do this split deployment, keep the backend on a trusted host or behind a firewall.

Docker

Enrai includes a portable Docker runtime and a published image on Docker Hub.

Pull the image:

docker pull agentrouter/enroi:latest

If you want to build it yourself from this repository:

docker build -t agentrouter/enroi:latest .

Run the container:

docker run --rm -it \
  -p 3001:3001 \
  -e EDITOR_WORKDIR=/workspace \
  -e OPENAI_API_KEY=your_key_here \
  -v "$(pwd)/backend/projects:/workspace" \
  agentrouter/enroi:latest

Container URL:

http://localhost:3001/editor

Use a different host port while keeping Enrai listening on 3001 inside the container:

docker run --rm -it \
  -p 3009:3001 \
  -e EDITOR_WORKDIR=/workspace \
  -e ENRAI_PUBLIC_URL=http://localhost:3009 \
  -e OPENAI_API_KEY=your_key_here \
  -v "$(pwd)/backend/projects:/workspace" \
  agentrouter/enroi:latest

Container URL:

http://localhost:3009/editor

Docker is the right fit when you want:

• reproducible local or internal deployments
• a packaged runtime with zsh, fish, and codex already available
• a mounted host folder that becomes the active workspace

The image already contains:

• portable frontend runtime
• Express backend
• zsh
• fish
• oh-my-zsh
• codex

Notes:

• If you use the published image, you do not need to build the frontend yourself first.
• The image builds the portable frontend during docker build only if you build it from source.
• The runtime serves the app from the embedded Express backend.
• Mount a host directory if you want persistent project files inside the workspace.
• -p HOST:CONTAINER must point to the port Enrai actually uses inside the container.
• If you also want the container itself to listen on another port, set -e PORT=... and match the published container port.
• If you want startup logs and callbacks to reflect the external host URL, also set -e ENRAI_PUBLIC_URL=....

Build from source

If you want to copy, fork, or modify Enrai and build it yourself:

npm install
cd backend && npm install && cd ..
npm run build:portable
npm run start:portable

If you want to build only the frontend:

cd frontend
npm install
npm run build
npm run start

If you want to run the backend separately:

cd backend
npm install
npm run dev

If you use a split deployment, make sure the frontend gets:

NEXT_PUBLIC_EDITOR_BACKEND_URL=https://your-backend.example.com

If you also want the docs app:

cd documentation
npm install
npm run build
npm run start

PM2

For a long-running internal deployment:

npm run build:portable
npm run pm2:start
pm2 save
sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u "$USER" --hp "$HOME"

Useful commands:

npm run pm2:logs
npm run pm2:restart
npm run pm2:stop

Notes

• The backend can read and write real project files.
• The terminal can execute commands directly in the workspace.
• Codex sessions can modify files and run tools in the selected workdir.
• If Enrai is exposed beyond a trusted internal network, add authentication and access control yourself.

For the full trust model and suggested controls, see Security.