Bruno: Deployment and Usage Guide

1. Prerequisites

Before installing Bruno, ensure you have the following:

Node.js (v16 or higher) - JavaScript runtime
npm (v8 or higher) - Node package manager (comes with Node.js)
Git - Version control system for cloning the repository
Electron (handled automatically) - Desktop application framework
Operating System: Windows, macOS, or Linux

2. Installation

Clone and Setup

# Clone the repository
git clone https://github.com/usebruno/bruno.git

# Navigate to the project directory
cd bruno

# Install dependencies
npm install

Alternative Installation Methods

Bruno is also available as a desktop application for all major platforms:

Windows: Download .exe installer
macOS: Download .dmg or .zip
Linux: Download .AppImage or use Snap Store

3. Configuration

Environment Variables

Bruno supports environment configuration through:

Global Environment Variables: Available across all collections
Collection Variables: Specific to individual collections
Local Environment Variables: For current session only

Configuration Files

Bruno collections are stored in plain text files using the .bru format:

Collections are organized in folders
Each request is a .bru file
Environments are stored as .bru.env files
Uses human-readable Bru language for scripting

API Keys and Authentication

Bruno supports various authentication methods:

API Key (header, query parameter)
Bearer Token
Basic Auth
OAuth 1.0/2.0
AWS Signature
Digest Auth

Configure authentication in request headers or parameters using environment variables:

// Example using Bru scripting
bru.setEnvVar("api_key", "your-api-key-here");

4. Build & Run

Development Mode

# Start the development server
npm run dev

# Or start with specific configuration
npm run electron:dev

Production Build

# Build for current platform
npm run build

# Build for all platforms
npm run build:all

# Package the application
npm run package

Running Tests

# Run test suite
npm test

# Run with coverage
npm run test:coverage

5. Deployment

Desktop Application Deployment

Since Bruno is an Electron-based desktop application, deployment options include:

Direct Distribution:
- Package as platform-specific installers
- Distribute via website downloads
- Use auto-update mechanisms
Package Managers:
- Homebrew (macOS): brew install bruno
- Snap Store (Linux): snap install bruno
- Chocolatey (Windows): choco install bruno
App Stores:
- Microsoft Store (Windows)
- Mac App Store (macOS)
- Flathub (Linux)

Cloud-Based Alternatives

For team collaboration, consider:

Bruno Cloud (official hosted version)
Self-hosted Bruno server (if available)
Git-based collection sharing

Import/Export Capabilities

Bruno supports importing from:

Postman (via converter utilities)
OpenAPI/Swagger (JSON/YAML)
Insomnia (v4 format)
WSDL (SOAP services)

Use the bulk import feature in the sidebar to migrate existing collections.

6. Troubleshooting

Common Issues and Solutions

1. Installation Fails

# Clear npm cache and retry
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

2. Build Errors

Ensure Node.js version is v16+
Check Electron dependencies: npm list electron
Verify native modules are compatible with your OS

3. Import Issues

If Postman/OpenAPI imports fail:

Verify the source file format is valid
Check for unsupported features in source collection
Use the converter utilities directly:

import { postmanToBruno } from 'utils/importers/postman-collection';
import { convertOpenapiToBruno } from 'utils/importers/openapi-collection';

4. Environment Variables Not Working

Verify variable scope (global vs collection vs local)
Check for naming conflicts
Ensure variables are properly interpolated using bru.interpolate()

5. Script Translation Issues

When migrating from Postman, some scripts may need manual adjustment:

// Postman syntax
pm.environment.get("variable");

// Bruno equivalent
bru.getEnvVar("variable");

Refer to the translator utility in postman-to-bruno-translator.js for complete mapping.

6. Theme Configuration Problems

If custom themes aren't working:

Verify theme schema compliance with oss.js
Check color format (hex, rgb, named colors)
Ensure all required properties are defined

7. Response Examples Not Saving

Verify collection has write permissions
Check if item has a draft version
Ensure example UID is generated using uuid()

Getting Help

GitHub Issues: Report bugs and request features
Documentation: Visit docs.usebruno.com
Community: Join discussions on GitHub or Discord
Source Code: Refer to the converter utilities and reducer examples provided in the codebase

Debug Mode

Enable debug logging for troubleshooting:

# Run with debug flags
npm run dev --debug

# Or set environment variable
DEBUG=bruno:* npm run dev

How to Deploy & Use bruno