Deployment

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

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

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.

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 now includes a root Dockerfile for the portable runtime.

Build the image:

docker build -t enrai/editor:latest .

Run the container:

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

Container URL:

http://localhost:3001/editor

Notes:

• The image builds the portable frontend during docker build.
• The runtime serves the app from the embedded Express backend.
• Mount a host directory if you want persistent project files inside the workspace.

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.