Quick Start

This guide takes you from zero to a working Opengram instance in a few minutes.

Prerequisites

Linux or macOS
Node.js 20+ -- install it from nodejs.org or with a version manager like fnm or nvm

1. Install Opengram

Option A: Install script (recommended)

curl -fsSL https://opengram.sh/install | sh

The script will:

Verify that Node.js 20+ is installed.
Detect your package manager (pnpm, bun, or npm).
Install the opengram CLI globally.
Launch the setup wizard (opengram init).

If you prefer to skip the wizard during install, pass --no-prompt:
curl -fsSL https://opengram.sh/install | sh -s -- --no-prompt
You can run opengram init later to configure.

Option B: Install via npm

npm install -g @opengramsh/opengram

Then run the setup wizard:

opengram init

2. Setup wizard

The install script automatically runs opengram init. If you skipped it or want to change your settings, you can re-run it at any time:

opengram init

The wizard will prompt you for:

Port -- the port Opengram listens on. Auto-detects an available port (tries 3000, 3001, 3333).
Instance secret -- a secret key used to authenticate API requests from your agents. Can be auto-generated, custom, or disabled.
Auto-rename -- whether to automatically rename chats using an LLM. Supports Anthropic, OpenAI, Google Gemini, xAI, and OpenRouter.
OpenClaw plugin -- if the openclaw CLI is detected, optionally install and connect the OpenClaw agent plugin.
Background service (Linux / macOS) -- whether to install a systemd or launchd service for automatic startup.

At the end, the wizard shows a Network section with instructions for making Opengram accessible from other devices using Tailscale. If Tailscale is already installed, it detects your hostname and shows the exact command to run.

The wizard writes its output to ~/.opengram/opengram.config.json (or $OPENGRAM_HOME/opengram.config.json). You can edit the file directly at any time. Re-running opengram init merges changes into the existing config without overwriting other settings.

3. Start the server

The wizard automatically starts Opengram at the end -- either via the background service (if you opted in) or directly in the foreground.

To verify that everything is working:

curl -fsS http://localhost:3000/api/v1/health
# → {"status":"ok"}

If you need to start Opengram again later, use:

opengram start

4. Access the UI

Open your browser and navigate to http://localhost:3000 (or the port you chose). You should see the Opengram chat interface.

5. 🦞 Connect your OpenClaw agents (optional)

If you use Openclaw, you can connect your agents to Opengram with our plugin. If the openclaw CLI was detected during opengram init, this is already configured -- otherwise, install the plugin manually:

npm install -g @opengramsh/openclaw-plugin
openclaw opengram setup

The setup command will ask for your Opengram base URL and instance secret, then configure OpenClaw to send and receive messages through the Opengram chat UI automatically.

See OpenClaw Plugin for more details.

6. Connect your other agents

To connect your own AI agent, you will use the Opengram REST API. Your agent will:

Poll for or receive dispatched messages.
Send responses back (including streamed tokens).

Here is a minimal example that claims a dispatch and sends a reply:

const BASE = "http://localhost:3000/api/v1";
const HEADERS = {
  Authorization: "Bearer og_your-secret-here",
  "Content-Type": "application/json",
};

// Claim a dispatch (long-polls for up to 10s)
const res = await fetch(`${BASE}/dispatch/claim`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({ workerId: "worker-1", leaseMs: 30000, waitMs: 10000 }),
});

if (res.status === 204) {
  // No work available, try again
} else {
  const { batchId, chatId, compiledContent } = await res.json();

  // Send a response message
  await fetch(`${BASE}/chats/${chatId}/messages`, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify({
      role: "agent",
      senderId: "assistant",
      content: `Echo: ${compiledContent}`,
    }),
  });

  // Complete the dispatch
  await fetch(`${BASE}/dispatch/${batchId}/complete`, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify({ workerId: "worker-1" }),
  });
}

See Building an Agent for a complete walkthrough including streaming and heartbeats.

Directory layout

After setup, Opengram stores everything under ~/.opengram/ (or the path set by $OPENGRAM_HOME):

~/.opengram/
  opengram.config.json   # Configuration
  data/
    opengram.db          # SQLite database
    uploads/             # Uploaded files

opengram.config.json is the main configuration file written by the setup wizard. See Configuration for details.
data/ holds all persistent state -- the SQLite database and uploaded files. Back up this directory to preserve everything.

Database migrations

Migrations run automatically when the server starts. No manual migration step is needed -- on upgrades, new migrations are applied on the next startup.

On this page