topgun (TopGunBuild/topgun)

topgun (TopGunBuild/topgun) | MoltPulse

npx create-topgun-app my-app
cd my-app && pnpm install && pnpm dev

npx @topgunbuild/server

pnpm start:server

docker pull ghcr.io/topgunbuild/topgun-server:latest
docker run -p 8080:8080 -e TOPGUN_NO_AUTH=1 ghcr.io/topgunbuild/topgun-server:latest

export DATABASE_URL=postgres://user:pass@host:5432/topgun

export JWT_SECRET=<random-32-byte-secret>     # Required for signed tokens
export TOPGUN_NO_AUTH=0                       # 0 = enforce auth, 1 = dev-only bypass
# ACL config: see /docs/security for per-map and per-op rules

docker compose up --build
# Or start the server directly (no Rust toolchain required)
npx @topgunbuild/server
# Contributor / monorepo path (has cargo):
# cargo run --bin topgun-server --release

import { TopGunClient } from '@topgunbuild/client';
import { IDBAdapter } from '@topgunbuild/adapters';

const client = new TopGunClient({
  serverUrl: 'ws://localhost:8080',  // optional — omit for local-only
  storage: new IDBAdapter(),
});
client.start();

// Reactive read — fires immediately and on every change
const todos = client.getMap('todos');
todos.subscribe((entries) => render(entries));

// Optimistic write — applies locally, syncs in background
todos.set('todo-1', { text: 'Buy milk', done: false });

import { TopGunProvider, useQuery, useClient } from '@topgunbuild/react';

function App() {
  return (
    <TopGunProvider client={client}>
      <TodoList />
    </TopGunProvider>
  );
}

function TodoList() {
  const client = useClient();
  const { data, loading } = useQuery('todos');

  if (loading) return <div>Loading...</div>;

  const toggleTodo = (todo) => {
    const todosMap = client.getMap('todos');
    todosMap.set(todo.id, { ...todo, done: !todo.done });
  };

  return (
    <ul>
      {data.map((todo) => (
        <li key={todo.id} onClick={() => toggleTodo(todo)}>
          {todo.text}
        </li>
      ))}
    </ul>
  );
}

import { useHybridSearch } from '@topgunbuild/react';

function DocSearch({ query }: { query: string }) {
  const { results, loading } = useHybridSearch('docs', query, {
    methods: ['fullText', 'semantic'],  // HybridSearchMethod: 'exact' | 'fullText' | 'semantic'
    k: 10,
    minScore: 0.3,
  });

  if (loading) return <p>Searching…</p>;

  return (
    <ul>
      {results.map((r) => (
        <li key={r.key}>
          {r.key} — score {r.score.toFixed(3)}
          <small>
            {' '}(BM25: {r.methodScores?.fullText?.toFixed(3)},
            semantic: {r.methodScores?.semantic?.toFixed(3)})
          </small>
        </li>
      ))}
    </ul>
  );
}

# Start the server — no Rust toolchain required
npx @topgunbuild/server

# Or start with Docker (includes Postgres)
docker compose up --build

# Contributor / monorepo path (has cargo):
# cargo run --bin topgun-server --release

# Or run the example app
cd examples/notes-app
pnpm install
pnpm start

pnpm test:k6:smoke

pnpm test:k6:throughput

pnpm --filter @topgunbuild/core bench

{
  "mcpServers": {
    "topgun": {
      "command": "npx",
      "args": ["@topgunbuild/mcp-server"],
      "env": {
        "TOPGUN_URL": "ws://localhost:8080"
      }
    }
  }
}

topgun

MoltPulse

TopGun

Key features

Quick start

Drop-in (5 minutes)

Pull pre-built image (Docker)

Production

Hybrid search (vector + full-text + exact)

Documentation

Packages

Running locally

Performance

Coming from X

Performance Testing

Quick Smoke Test

Full Throughput Benchmark

Micro-Benchmarks (CRDT operations)

AI Agents

Contributing

Community

TopGun v1

Ecosystem Role

Embed Badge