Skip to content
Cosmictron Docs

Quick Start

This guide walks you from zero to a running Cosmictron agent in under 5 minutes.

Prerequisites

Section titled “Prerequisites”
  • Rust 1.85+ — rustup install 1.85
  • WASM target — rustup target add wasm32-unknown-unknown
  • Bun (optional, for TypeScript SDK) — curl -fsSL https://bun.sh/install | bash

Build and install

Section titled “Build and install”

  1. Clone and build

    Terminal window
    git clone https://github.com/cosmictron/cosmictron
    cd cosmictron
    cargo build --release -p cosmictron-server --bin cosmictron-server
    cargo build --release -p cosmictron-cli    --bin cosmictron-cli
    # Binaries land in target/release/

  2. Create an agent project

    Terminal window
    cosmictron-cli create my-agent --template agent
    cd my-agent

    This scaffolds a Rust WASM module with:

    • AgentState table for recording agent messages
    • McpToolCall table for MCP tool invocation tracking
    • Reducers: record_agent_message, record_tool_call, complete_tool_call

  3. Start the dev server

    Terminal window
    # Hot-reload mode (rebuilds module on file changes)
    COSMICTRON_MODULE_PATH=src/lib.rs cosmictron-cli dev --hot-reload
    

    # Or start without hot reload
    cosmictron-cli start

  4. Build and deploy your module

    Terminal window
    cargo build --target wasm32-unknown-unknown --release
    cosmictron-cli deploy \
      target/wasm32-unknown-unknown/release/my_agent.wasm \
      --name my-agent

  5. Connect from TypeScript

    import { CosmictronClient } from '@cosmictron/client';
    

    const client = new CosmictronClient('ws://localhost:3000');
    await client.authenticate();
    

    // Send a message to the agent
    await client.callReducer('record_agent_message', {
      id: 'msg-1',
      role: 'user',
      content: 'Hello agent!'
    });
    

    // Subscribe to agent state
    const sub = await client.subscribe('SELECT * FROM agent_state');
    sub.on('update', (delta) => {
      console.log('Agent state changed:', delta.inserts);
    });

Next steps

Section titled “Next steps”